Bees

Bees - Lightweight SQLite-Backed Issue Tracker

This skill activates when working with Bees for issue tracking, dependency management, and AI-augmented workflows.

When to Use This Skill

Activate when:

• Managing issues with dependencies in a local repository
• Exporting issue context for AI agents (bees list --json, bees show --json)
• Tracking issue hierarchies and dependency graphs
• Needing SQLite-backed performance for large issue sets
• Syncing issues to JSONL for portability (bees sync)
• Working with AI agents that need structured task queues

What is Bees?

Bees is a lightweight, local-first issue tracker designed for AI-augmented development:

• SQLite storage: WAL-mode SQLite database for fast queries
• Single binary: Written in Zig, compiles to a small static binary
• AI-augmented: bees prime dumps a workflow cheatsheet for agents, bees sync exports JSONL, --json flags on read commands
• Dependency-aware: Query ready issues with bees ready, supports blocks/related/parent-child
• Local-first: No server required, everything stored in .bees/ directory

Installation

Install via mise: add [tools."github:ctxshift/bees"] with version = "latest" to mise.toml (see templates/mise.toml), then mise install. Full install matrix, platform asset patterns, pre-built binaries, and source build: references/installation.md.

Getting Started

Initialize Bees

bees init

Creates the .bees/ directory with SQLite database and configuration.

Create an Issue

bees create "Implement user authentication"

List Issues

bees list

Show Issue Details

bees show 

Close an Issue

bees close 

Find Ready Issues

bees ready

Returns issues with no unresolved dependencies.

Commands Reference

Per-flag syntax for the 13 day-to-day subcommands (create, list, show, update, close, ready, dep, label, comment, config, sync, import, prime): references/commands.md. bees 0.4.0 has 19 top-level commands; for the rest (upgrade, edit, rename-prefix, daemon, version, and the ls alias) run bees --help — except bees upgrade --help, which executes a real database migration instead of printing help (see Troubleshooting).

Dependency Management

Dependency Types

Bees supports three relationship types between issues. Argument order is a gotcha — the dependent issue comes first:

bees dep add             # id depends on blocker-id

| Type | Flag | Behavior | |------|------|----------| | blocks | -t blocks (default) | Prevents bees ready from showing dependent issue | | related | -t related | Informational link, no blocking | | parent | -t parent | Parent-child hierarchy |

Ready Queue

bees ready returns issues where:

• Status is open
• No open blocks dependencies remain

Only blocks-type dependencies gate readiness. parent-child and related dependencies never do — a child issue stays in bees ready whether its parent is open or closed (verified against bees 0.4.0). To make a child wait on its parent, add an explicit blocks edge.

Cycles are NOT rejected — check before adding a reverse edge

Bees does not detect circular dependencies. Both edges are accepted, and the pair then deadlocks: each blocks the other, so neither ever appears in bees ready.

bees dep add taskA taskB   # accepted
bees dep add taskB taskA   # ALSO accepted, exit 0 — no cycle error
bees ready                 # "No ready issues." — both are now unreachable

Verified against bees 0.4.0. Inspect bees dep list before adding an edge in the reverse direction; nothing else will stop you.

AI Integration

bees sync (JSONL Export)

Export all issues to JSONL for external tooling:

bees sync
# Writes .bees/issues.jsonl

The JSONL file contains one JSON object per line, compatible with standard data processing tools.

bees prime (Agent Workflow Cheatsheet)

Dump the static workflow-context cheatsheet for AI agents:

bees prime

The output is a fixed markdown dump of workflow rules and essential commands — it contains no issue data (verified against bees 0.4.0: a repo with 4 issues produced zero mentions of any issue id). It takes no flags. For issue context — titles, descriptions, labels, dependencies, status — use bees list --json and bees show --json.

--json flag coverage and jq scripting recipes: references/commands.md.

Storage and File Structure

.bees/
├── bees.db          # SQLite database (WAL mode) - primary storage
├── issues.jsonl     # JSONL export (created by bees sync)
├── metadata.json    # Repository metadata
├── config.json      # Local configuration
└── .gitignore       # Excludes bees.db from version control

SQLite as Primary Storage

Unlike beads (which uses JSONL as primary with SQLite cache), bees uses SQLite as the primary data store:

• WAL mode for concurrent read access
• bees sync exports to JSONL for portability
• bees import rebuilds the database from issues.jsonl (drops and re-creates bees.db) — use after pulling a new issues.jsonl

Workflow Examples

PR-Based Development Workflow

Session Start

git checkout main && git pull
bees ready                       # Find available issues
bees show                    # Read requirements

Issue Execution

git checkout -b feature/
bees update  --status in_progress

# Do the work:
# - Read existing code to understand patterns
# - Implement following project conventions
# - Run quality gates (tests, linters, formatters)

git add 
git commit -m "type(scope): description"

PR Creation

git push -u origin 
gh pr create --title "type(scope): description" --body "- Change one
- Change two"

Watch CI and Close

gh pr checks --watch
bees close 
git add .bees/ && git commit -m "chore(bees): close "
git push

Cleanup

After user merges:

git checkout main && git pull
git branch -d 
bees ready                       # Find next issue

AI Agent Task Loop

An automated task-loop script (poll bees ready --json, work, close, sync): references/commands.md.

Bees vs Beads

| Feature | Bees | Beads | |---------|------|-------| | Storage | SQLite (WAL mode) | JSONL + SQLite cache | | Language | Zig | Go | | Binary | Single static binary | Go binary | | Sync model | One-directional export (bees sync) | Bidirectional git sync (bd sync/bd pull) | | AI context | bees prime (static workflow cheatsheet); issue data via --json flags | --json flags only | | Init modes | Local-first only | Full, stealth, contributor | | Comments | bees comment add | bd comment | | Dependency types | blocks, related, parent (-t flag) | blocks only | | Rebuild from JSONL | bees import | bd rebuild |

Best Practices

Priorities and Labels

type:bug, type:feature, type:chore
priority:high, priority:medium, priority:low
status:wip, status:blocked, status:review
sprint:42, epic:auth
skill:git, skill:security, skill:rust
complexity:trivial, complexity:complex

Complexity labels (drives the pipeline decision)

Bees issues carry one of two complexity labels. The label tells the picker whether to dispatch a single agent or the full five-tier pipeline:

• complexity:trivial → dispatch one haiku worker (see "Workflow Examples")
• complexity:complex → dispatch the five-tier pipeline internally (see /core:agent-loop "Five-Tier Decomposition Pipeline")

Apply with bees label add , one label per invocation — bees update has no --labels flag, and a comma-separated string becomes a single literal label. Adding a priority:pN label does not change the issue's priority field; set that separately with bees update -p .

Bees never carries team:* labels. The five tier names (team:opus-planner, team:sonnet-test, team:sonnet-impl, team:haiku-ci, team:opus-review) are dispatch-time strings the Sub-team Leader puts inside each Task spawn prompt. They identify the stage being dispatched, not the bees row.

One bees issue == one slice. A complex slice still gets ONE bees issue; the five pipeline stages produce intermediate artifacts (bees comments on the same issue, git commits, PR comments), not five chained bees rows.

Dependencies

• Keep dependency chains shallow ( --json`
• Use bees ready --json for automated task queue polling
• Use bees sync to create portable JSONL snapshots
• Close issues atomically after completion

Comments

Use bees comment add to record progress notes:

bees comment add  "Completed initial implementation"
bees comment list 

Claude-teams-aware bee format

Bees that an agent loop picks up directly need structured labels and a structured description body. Single-paragraph bees are appropriate for operator-only notes; agent-targeted bees follow this shape:

Labels (apply via bees label add , one label per call; set priority itself with bees update -p ):

• team:* — the agent team that owns the work (e.g., team:opus-planner, team:sonnet-impl)
• skill:: — domain skills the worker loads (e.g., skill:elixir:phoenix)
• model: — initial model assignment (model:haiku, model:sonnet, model:opus)
• complexity:trivial OR complexity:complex — pipeline-decision label
• priority:p — keeps bees ready queue order

Description sections (markdown H2 or H3):

• ## CRITICAL — must-not-violate constraints (one bullet per line)
• ## Objective — what success looks like
• ## Context — existing code, prior commits, related PRs
• ## Acceptance criteria — bullet list, testable
• ## Deliverables — concrete artifacts (files, PRs, commits)
• ## Load skills — exact skill names the worker invokes

Single-writer constraint

The SQLite database under .bees/bees.db is single-writer. Concurrent workers MUST NOT run bees create, bees close, bees update, bees label add, or bees dep add directly — concurrent writes raise SQLITE_CONSTRAINT or daemon.lock failures that lose work.

Workers collect proposed writes in their final report (a ## BEES REQUESTS section). The lead applies the queued writes through a single serial writer — the bees-manager agent (see agents/bees-manager.md).

bees ready as canonical queue

bees ready (run from the repo root that owns the .bees/ directory) is the canonical ordering of "what an agent picks up next". Edit the queue order via bees (priority:pN label OR bees dep add), never by mutating storage out-of-band. Downstream systems that synchronize bee state to other trackers read bees ready order; raw-database edits skip the synchronization layer and leave consumers stale.

Troubleshooting

Database Issues

# Check database integrity
sqlite3 .bees/bees.db "PRAGMA integrity_check;"

# Database is locked
# Ensure no other process has an exclusive lock
lsof .bees/bees.db

bees upgrade --help runs the migration

bees upgrade --help does not print help — it executes the real upgrade (refreshes .bees/.gitignore and applies schema migrations to bees.db), verified against bees 0.4.0. Do not probe upgrade with --help on a tracker you are not ready to migrate.

Build Issues (from source)

Troubleshooting for source builds lives with the build instructions: references/installation.md.

JSONL Out of Sync

If issues.jsonl is stale, regenerate:

bees sync

References

• references/commands.md: Per-flag syntax for the 13 day-to-day subcommands, --json output, jq scripting recipes, and the agent task-loop script
• references/installation.md: Install matrix (mise, pre-built binaries, source build) and build troubleshooting
• references/teams-integration.md: Protocol for mirroring bees issues into Claude's task list for Agent Teams coordination
• references/migration-from-beads.md: Guide for migrating from beads to bees
• references/skill-catalog.md: Marketplace-wide skill catalog with keyword triggers for matching tracker issues to skills

Paired agents

• agents/bees-manager.md: Serial writer for bees DBs. Use when concurrent workers need to apply queued bees writes through a single SQLite writer to avoid SQLITE_CONSTRAINT and daemon.lock failures.
• agents/bees-worker.md: Processes bees issues by polling bees ready, executing work, and syncing results. Use for automating issue queues or AI-driven workflows.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: vinnie357
• Source: vinnie357/claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.