Task tracking, spec-driven planning, and knowledge injection for AI coding agents.

tbd (short for “To Be Done,” or “TypeScript beads” if you prefer) combines four things that are each powerful on their own but work even better together:

1. Task tracking (beads): Agent-friendly, CLI-native issue tracking for bugs, features, epics, and dependencies that persist across sessions in git. This alone is a step change in what agents can do. Beads are fantastic and unreasonably effective at scaling an agent’s capacity from ~5-10 ad-hoc tasks to hundreds of structured beads.
2. Spec-driven planning: Templates and workflows for writing specs, breaking them into beads, and implementing systematically. With a good spec and beads, you can leave an agent running overnight and come back to solid code.
3. Knowledge injection: Instant availability of in-depth engineering guidelines and rules docs. These are essentially “self-injected context” for an agent to get smarter when it needs it.
4. Shortcuts: Reusable instructions for common tasks like code review, PR creation, and writing planning specs, architecture docs, and research briefs.

tbd comes pre-installed with in-depth guidelines docs on many topics, including TypeScript and Python best practices and common agent pitfalls, red-green TDD, golden testing, Convex, monorepo project setup, error handling practices, and backward compatibility rules. (But you can use your own guidelines if you prefer.)

I use tbd most frequently in Claude Code since it’s most powerful as a skill, but it will work in Cursor, Codex, or any agent environment that can use the tbd CLI.

That’s it. Running tbd prime gives agents full workflow context on how to use tbd and how to help you. It will then bootstrap a SKILL.md into your project by running tbd setup --auto (which will add a .tbd directory and add itself to your .claude skills and hooks). And then it will use shortcuts to welcome you and get you started.

Running tbd with no arguments shows help with a prominent reminder for agents to run tbd prime.

You can then always ask questions like: “what can I do with tbd?”

You can use tbd as a drop-in replacement for the original Beads (bd). It’s largely compatible at the CLI level for core issue tracking functionality.

Despite the general power of the beads, there are quite a few practical frustrations with the original Beads implementation—notably the daemon modifying files, merge conflicts, sync confusions across branches and database, and SQLite not working on network drives, such as Claude Code Cloud. After using bd for over a month, this became my greatest pain point. I now use tbd for all my agent coding and its sync architecture works pretty well.

What excites me now is that tbd is more than just task management.

These workflows arose from several months of heavy spec-driven agentic coding. With better use of specs, what you build is far clearer and more maintainable. In fact, I think of iterating on a spec as the hard part now. Writing the code is often almost automatic, if a spec is good enough!

Basically 100% of the code I now write is agent-written, planned and tracked through specs and beads and streamlined with shortcuts.

To help with this, tbd provides a way to inject engineering rules and best practices and streamline reproducible workflows with shortcuts.

By combining task management, knowledge injection, and shortcuts, I find my agents ship code with speed, quality, and discipline.

Once you start doing things like the above workflows, it gets repetitive. And I like to now use voice to give prompts. So having “shortcut” docs that list common tasks is really helpful.

I can now ship entire large features just with voice prompts like “use the shortcut to create a new plan spec that …” and “now use the shortcut to file a PR with a validation plan.”

tbd focuses on the durable layer of agent development: issue tracking, planning, and knowledge that persist in git across sessions. It does not (yet) try to solve real-time multi-agent coordination features of Beads or Gas Town or Agent Mail or unstructured agent loops like Ralph Wiggum. These seem great for rapid prototyping, but so far, code where quality or scale matters, I’ve not fully embraced unstructured automation (e.g. 20+ concurrent agents or Ralph loops). I find having more process and discipline around specs (and around 6–8 concurrent agents handling different aspects that I manage) is slower, because it forces you to design, but it gives higher quality results.

You talk to your agent in natural language. The agent translates your requests into tbd commands.

The tbd CLI blends task tracking and context injection. Some tbd commands do things, like create or update beads, and some help the agent get status or context or knowledge and know what to do next:

Under the hood, your agent runs these tbd commands automatically. You just talk naturally.

• Git-native: Beads live in your repo, synced to a separate, dedicated tbd-sync branch. Your code history stays clean—no bead churn polluting your logs.
• Agent friendly: JSON output, non-interactive mode, simple commands that agents understand. Installs itself as a skill in Claude Code.
• Markdown + YAML frontmatter: One file per bead, human-readable and editable. This eliminates most merge conflicts.
• Beads alternative: Largely compatible with bd at the CLI level, but with a simpler architecture: no JSONL merge conflicts, no daemon modifying your working tree, no SQLite file locking on network filesystems (see FAQ: How does tbd compare to Beads?).
• Shortcuts: Over a dozen reusable workflow documents—plan specs, code reviews, commit processes, PR creation, research briefs, and more.
• Guidelines: 20+ guideline docs of coding rules and best practices (see Built-in Engineering Knowledge).
• Templates: Document templates for planning specs, research briefs, architecture docs.

Engineers are still adjusting to how fast things are changing. But the reality is that most of the time now, if you’re doing it right, agents should write 100% of your code.

But anyone who’s coded a lot with agents knows they can be very bad or very good, depending on the situation. Without structure and knowledge, the results are often slop or have critical flaws or they don’t scale to large projects. They forget conventions between sessions, skip testing, and don’t follow your team’s patterns.

The usual tactics like pasting rules into prompts is fragile and tiring. And even adding all these rules to CLAUDE.md or AGENTS.md doesn’t scale.

Beads (git-native CLI-based issue tracking) is one element of the solution. It solves the task management problem brilliantly. If you’re not using beads already, you should be!

But task tracking alone doesn’t help with planning or quality. You still need a way to think through what you’re building before you start, and a way to make sure the agent follows good engineering practices while it works.

tbd combines all three: beads for task management, spec-driven workflows for planning, and curated engineering guidelines for quality. Together, they let you hand an agent a well-defined spec with clear beads and expert knowledge, and get back careful, well-structured code—even overnight, even across sessions.

My current favorite workflows and guidelines are included by default, but you’re not locked in. Add your own via --add or configure what’s available in .tbd/config.yml.

And yes, all the code and all the specs of tbd are agent written—see the FAQ.

When you run tbd setup, your agent gets instant access to 20+ guideline documents covering real-world engineering practices. These aren’t generic tips; they’re mostly my own detailed and sometimes opinionated rules with concrete examples, built from months of heavy agentic coding.

Plus guidelines on coding rules, comment quality, commit conventions, and style.

You can also add your own team’s guidelines from any URL:

tbd guidelines --add=<url> --name=my-team-rules

Requirements:

• Node.js 20+
• Git 2.42+ (for orphan worktree support)

npm install -g get-tbd@latest

# Fresh project (--prefix is REQUIRED—2-8 alphabetic chars, e.g. myapp-a1b2)
tbd setup --auto --prefix=myapp

# Joining an existing tbd project (no prefix needed—reads existing config)
tbd setup --auto

# Migrate from Beads (uses your existing beads prefix)
tbd setup --from-beads

Tip: Run tbd setup --auto anytime to refresh skill files, hooks, and configs with the latest shortcuts, guidelines, and templates.

tbd is designed for teams where one person sets up the project and others join later.

First contributor:

npm install -g get-tbd@latest
tbd setup --auto --prefix=myproject
git add .tbd/ .claude/ && git commit -m "Initialize tbd"
git push

Joining contributors:

git clone <repo>
npm install -g get-tbd@latest
tbd setup --auto                    # No --prefix needed—reads existing config

tbd setup --auto configures SessionStart hooks that run at the beginning of each Claude Code session:

• tbd prime—injects workflow context so the agent knows how to use tbd
• ensure-gh-cli.sh—installs the GitHub CLI (gh) if not already available

GitHub authentication: For gh to work, set these environment variables before starting your agent session:

GH_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
GH_PROMPT_DISABLED=1

Create a Personal Access Token (fine-grained recommended) with Contents and Pull requests read/write permissions. For Claude Code Cloud, set these in your project’s environment variables. For local CLI usage, add them to your shell profile (~/.zshrc or ~/.bashrc). See the setup-github-cli shortcut for details.

To disable automatic gh installation, pass --no-gh-cli during setup or set use_gh_cli: false in .tbd/config.yml under settings:.

tbd setup --from-beads       # Auto-detects and migrates
tbd stats                    # Verify
tbd list --all
tbd setup beads --disable    # Optionally disable beads after migration

Issue IDs are preserved: proj-123 in beads becomes proj-123 in tbd.

tbd ready                      # Beads ready to work on (open, unblocked, unassigned)
tbd list                       # List open beads
tbd list --all                 # Include closed
tbd list --specs               # Group beads by spec
tbd show proj-a7k2             # View bead details
tbd create "Title" --type=bug  # Create bead (bug/feature/task/epic/chore)
tbd update proj-a7k2 --status=in_progress
tbd close proj-a7k2            # Close bead
tbd close proj-a7k2 --reason="Fixed in commit abc123"
tbd sync                       # Sync with remote (auto-commits and pushes)

tbd dep add proj-b3m9 proj-a7k2        # b3m9 depends on a7k2
tbd blocked                            # Show blocked beads
tbd label add proj-a7k2 urgent backend
tbd label remove proj-a7k2 urgent
tbd label list                         # All labels in use
tbd search "authentication"            # Search beads

tbd bundles three types of documentation your agent can invoke on demand:

# Shortcuts—workflow instructions
tbd shortcut --list              # List all shortcuts
tbd shortcut new-plan-spec       # Get the plan spec workflow

# Guidelines—coding rules and best practices
tbd guidelines --list            # List all guidelines
tbd guidelines typescript-rules  # Get TypeScript rules

# Templates—document scaffolds
tbd template --list              # List all templates
tbd template plan-spec           # Get a plan spec template

# Add your own from any URL
tbd guidelines --add=<url> --name=<name>
tbd shortcut --add=<url> --name=<name>
tbd template --add=<url> --name=<name>

Available shortcuts:

Available guidelines: See Built-in Engineering Knowledge for the full list of 20+ guidelines covering TypeScript, Python, testing, TDD, and more.

Available templates:

For non-trivial features, tbd supports a full spec-driven workflow:

1. Plan: Create a planning spec (tbd shortcut new-plan-spec)
2. Break down: Convert spec into implementation beads (tbd shortcut plan-implementation-with-beads)
3. Implement: Work through beads systematically (tbd shortcut implement-beads)
4. Validate: Create validation plan, run tests (tbd shortcut new-validation-plan)
5. Ship: Commit, create PR (tbd shortcut create-or-update-pr-with-validation-plan)

tbd status                   # Repository status (works before init too)
tbd stats                    # Bead statistics
tbd doctor                   # Check for problems
tbd doctor --fix             # Auto-fix issues

Every command supports these flags for automation:

tbd                          # Full orientation and workflow guidance
tbd readme                   # This file
tbd docs                     # Full CLI reference

Or read online:

• CLI Reference—Complete command documentation
• Design Doc—Technical architecture

tbd keeps two things separate from your code:

• Beads live on a dedicated tbd-sync branch. One Markdown file per bead means parallel creation never conflicts. tbd sync pushes changes—no manual git operations needed.
• Documents (shortcuts, guidelines, templates) are cached locally in .tbd/docs/ during tbd setup --auto. Your agent reads them on demand via tbd shortcut, tbd guidelines, and tbd template. Re-run tbd setup --auto anytime to refresh with the latest bundled docs, or add your own via --add.
• Everything is self-documented via the CLI. Running tbd shows help with quick command reference; tbd prime gives full workflow orientation. tbd setup --auto (idempotent, safe anytime) writes a skill file (SKILL.md/AGENTS.md) that teaches the agent all available commands, shortcuts, and guidelines. This means agents can inject context—specs, engineering guidelines, workflow instructions—at any point in a session, not just at startup.

See the design doc for details.

tbd was inspired by Beads by Steve Yegge, and I’m grateful for the idea—it genuinely changed how I work with agents. If you’re not familiar with Beads, the core insight is that git-native issue tracking raises an agent’s capacity for structured work from ~5-10 to-do items to hundreds of beads.

tbd builds on that foundation with a simpler architecture: plain Markdown files instead of JSONL, no daemon, no SQLite, no 4-way sync. This avoids the edge cases I ran into with network filesystems (Claude Code Cloud), merge conflicts, and multi-agent workflows.

If you already use Beads, tbd setup --from-beads migrates you to tbd. This imports and sets up your .tbd directory and preserves the IDs of all issues.

Scope: tbd focuses on the durable layer—issue tracking, specs, and knowledge that persist across sessions and live in git. It does not aim to solve real-time multi-agent coordination, which is a separate problem requiring sub-second messaging and atomic claims. Tools like Agent Mail and Gas Town address that space and are complementary to tbd—you could layer real-time coordination on top of tbd's durable tracking. See the design doc for a detailed comparison.

After months of heavy agentic coding, I’ve found that the single biggest lever for quality is planning before you code. A carefully written spec lets you think through what you’re building, catch design problems early, and break the work into well-defined beads. The agent then implements each bead with clear context about the bigger picture.

This matters because with a good spec broken into beads, you can leave an agent running overnight and come back to code that’s well-structured and coherent—not a pile of disconnected changes. tbd bakes in shortcuts for the full cycle: writing specs, breaking them into beads, implementing, validating, and shipping.

Of course! I bootstrapped with the original bd. It imported from bd and began self-hosting its own tasks, then took over its own specs and reminds itself of its own coding guidelines. Here’s what that looks like in practice:

Specs: tbd has dozens of active and completed plan specs, such as:

• plan-2026-01-15-tbd-v1-implementation.md—The original v1 design
• plan-2026-01-20-streamlined-init-setup-design.md—Redesigning the setup flow
• plan-2026-01-26-configurable-doc-cache-sync.md—Making the doc system configurable
• plan-2026-01-28-cli-add-docs-by-url.md—Adding --add for external docs

Beads: Features are broken into beads and worked through systematically. For example, the current list of open beads for this project looks like

$ tbd list --pretty 
tbd-0nuf      P2  ○ open  [feature] Add remote vs local issue counts to tbd stats
tbd-1r0w      P2  ○ open  [epic] Spec: CLI Output Formatting Consistency
...
tbd-pt3v      P2  ○ open  [epic] Spec: CLI Output Design System
tbd-tv5i      P2  ○ open  [feature] Format option (json/yaml/table/csv)
tbd-w4un      P2  ○ open  [task] Create claude-installation.md with installation section for Claude only
tbd-x3zq      P2  ○ open  [task] Add integration tests for shortcut command
tbd-x8va      P2  ○ open  [epic] Agent documentation consolidation and cleanup
tbd-xqn2      P2  ○ open  [feature] Issue templates
tbd-yom2      P2  ○ open  [feature] Improve sync commit messages with ticket IDs and summaries
├── tbd-f0nb      P2  ○ open  [task] Generate commit body with long-format issue summaries (title, description, close_reason)
├── tbd-qi6q      P2  ○ open  [task] Add tests for sync commit message generation
├── tbd-r6s8      P2  ○ open  [task] Track modified issues at commit time and pass to commit message generator
└── tbd-xdwv      P2  ○ open  [task] Generate commit subject line with up to 8 short IDs (truncate if >10)
tbd-z26l      P2  ○ open  [task] Document configuration options in tbd-design.md
tbd-6org      P3  ○ open  [task] Add ESLint rule to enforce atomically for file writes

39 issue(s)
$ 

Yes. tbd comes with 20+ bundled guidelines, but you can add your own team’s docs from any URL:

tbd guidelines --add=<url> --name=my-team-rules
tbd shortcut --add=<url> --name=my-team-workflow
tbd template --add=<url> --name=my-team-template

You can also configure which docs are available in .tbd/config.yml. I put my favorite guidelines and shortcuts in by default, but you’re not locked into using them.

See docs/development.md for build and test instructions.

MIT