beads
gastownhall/beads
Persistent task memory for AI agents—survives conversation compaction with dependency tracking across sessions.
What is beads?
Beads is a Dolt-backed issue tracker designed for multi-session AI work that persists through conversation compaction. Use it when your work spans multiple sessions, has task dependencies, or needs context recovery after model context resets.
- Track tasks with dependencies and blockers across multiple conversation sessions
- Survive conversation compaction with persistent memory stored in Dolt
- Claim and update work atomically with status tracking (open, in_progress, blocked, closed, deferred)
- Query unblocked work ready to start with `bd ready`
- Export structured JSON output for programmatic access to all commands
- Support advanced patterns like molecules (templates), async gates, and worktrees
How to install beads
npx skills add https://github.com/gastownhall/beads --skill beads- bd CLI v0.60.0 or later installed and in PATH
- Git repository (optional if using BEADS_DIR with --stealth mode)
- Run `bd init` once in project root (typically done by humans, not agents)
How to use beads
- 1.Run `bd ready --json` to find unblocked work at session start
- 2.Run `bd show <id> --json` to retrieve full context for a task
- 3.Run `bd update <id> --claim --json` to claim and start work atomically
- 4.Add notes to tasks as you work (critical for surviving compaction)
- 5.Run `bd close <id> --reason "..." --json` when task is complete
- 6.Run `bd dolt push` to sync to remote Dolt repository if configured
- 7.Use `bd create` to add new tasks with type, priority, and dependency flags
Use cases
- Resume a multi-week feature after conversation compaction by querying `bd list --status in_progress`
- Discover and track bugs found mid-task with automatic dependency linking
- Coordinate multi-session work with blockers by checking `bd ready` for unblocked tasks
- Recover full context after model reset using `bd show <id> --long` with persistent notes
- Manage complex projects with task templates (molecules) and async coordination gates
- AI coding agents (Claude Code, Codex) managing work across multiple sessions
- Teams using Dolt for collaborative task synchronization
- Developers needing persistent task state that survives context window resets
- Projects with complex task dependencies and blockers
beads FAQ
Use Beads ('bd') if you need context in 2+ weeks or have multi-session work with dependencies. Use TodoWrite for single-session linear tasks that don't need to survive compaction.
Run `bd list --status in_progress --json` to find in-progress tasks, then `bd show <id> --long` to retrieve full context including notes and dependencies.
Run `bd init <prefix>` in your project root to initialize the Beads database.
Yes—set BEADS_DIR environment variable and use `--stealth` flag to operate without Git.
Use `--deps` flag when creating tasks (e.g., `--deps blocks:oauth-id`) or update existing tasks with dependency relationships.
Full instructions (SKILL.md)
Source of truth, from gastownhall/beads.
name: beads description: > Dolt-powered issue tracker for multi-session work with dependencies and persistent memory across conversation compaction. Use when work spans sessions, has blockers, or needs context recovery after compaction. Trigger with "create task", "what's ready", "track this work", "resume after compaction". Make sure to use this skill whenever managing multi-session work, tracking dependencies, or recovering context. allowed-tools: "Read,Bash(bd:*)" version: "0.60.0" author: "Steve Yegge steve.yegge@gmail.com" license: "MIT" compatible-with: [claude-code, codex] tags: [issue-tracking, task-management, multi-session, dependencies]
Beads - Persistent Task Memory for AI Agents
Graph-based issue tracker that survives conversation compaction. Provides persistent memory for multi-session work with complex dependencies.
bd vs TodoWrite
Decision test: "Will I need this context in 2 weeks?" YES = bd, NO = TodoWrite.
| bd (persistent) | TodoWrite (ephemeral) |
|---|---|
| Multi-session, dependencies, compaction survival | Single-session linear tasks |
| Dolt-backed team sync | Conversation-scoped |
See BOUNDARIES.md for detailed comparison.
Prerequisites
bd --version # Requires v0.60.0+
- bd CLI installed and in PATH
- Git repository (optional — use
BEADS_DIR+--stealthfor git-free operation) - Initialization:
bd initrun once (humans do this, not agents)
CLI Reference
Run bd prime for AI-optimized workflow context (auto-loaded by hooks).
Run bd <command> --help for specific command usage.
Essential commands: bd ready, bd create, bd show, bd update, bd close, bd dolt push
Session Protocol
bd ready— Find unblocked workbd show <id>— Get full contextbd update <id> --claim— Claim and start work atomically- Add notes as you work (critical for compaction survival)
bd close <id> --reason "..."— Complete taskbd dolt push— Push to Dolt remote (if configured)
Output
Append --json to any command for structured output. Use bd show <id> --long for extended metadata. Status icons: ○ open ◐ in_progress ● blocked ✓ closed ❄ deferred.
Error Handling
| Error | Fix |
|---|---|
database not found | bd init <prefix> in project root |
not in a git repository | git init first |
disk I/O error (522) | Move .beads/ off cloud-synced filesystem |
| Status updates lag | Use server mode: bd dolt start |
See TROUBLESHOOTING.md for full details.
Examples
Track a multi-session feature:
bd create "OAuth integration" -t epic -p 1 --json
bd create "Token storage" -t task --deps blocks:oauth-id --json
bd ready --json # Shows unblocked work
bd update <id> --claim --json # Claim and start
bd close <id> --reason "Implemented with refresh tokens" --json
Recover after compaction: bd list --status in_progress --json then bd show <id> --long
Discover work mid-task: bd create "Found bug" -t bug -p 1 --deps discovered-from:<current-id> --json
Advanced Features
| Feature | CLI | Resource |
|---|---|---|
| Molecules (templates) | bd mol --help | MOLECULES.md |
| Chemistry (pour/wisp) | bd pour, bd wisp | CHEMISTRY_PATTERNS.md |
| Agent beads | bd agent --help | AGENTS.md |
| Async gates | bd gate --help | ASYNC_GATES.md |
| Worktrees | bd worktree --help | WORKTREES.md |
Resources
| Category | Files |
|---|---|
| Getting Started | BOUNDARIES.md, CLI_REFERENCE.md (live reference pointers), WORKFLOWS.md |
| Core Concepts | DEPENDENCIES.md, ISSUE_CREATION.md, PATTERNS.md |
| Resilience | RESUMABILITY.md, TROUBLESHOOTING.md |
| Advanced | MOLECULES.md, CHEMISTRY_PATTERNS.md, AGENTS.md, ASYNC_GATES.md, WORKTREES.md |
| Reference | STATIC_DATA.md, INTEGRATION_PATTERNS.md |
Validation
If bd --version reports newer than 0.60.0, this skill may be stale. Run bd prime for current CLI guidance — it auto-updates with each bd release and is the canonical source of truth (ADR-0001).
Related skills
More from gastownhall/beads and the wider catalog.
clanker-discipline
Catches state bloat, grab-bag models, and mutation ambiguity in AI-generated code.
skill-from-masters
通过真实案例创建高质量skill。先找黄金案例和失败案例，归纳什么有效什么无效，再用理论解释为什么。skill是干活的，要从实践中学习，不是从书本中学习。触发词："帮我创建一个skill"、"我想做一个skill来..."
md2wechat
Convert Markdown to WeChat Official Account HTML with formatting, drafts, and image generation.
ai-image-generation
Generate and edit images with 11+ AI models (FLUX 2, GPT Image 2, Seedream, Qwen, Wan) via RunComfy CLI.
ai-music
Generate AI music via RunComfy CLI—route to ElevenLabs premium vocals or cheap ACE Step, plus audio editing.
ai-video-generation
Generate videos from text or images using RunComfy's full model catalog—pick the right model for your intent.