tbd

Task tracking, spec-driven planning, and knowledge injection for AI coding agents—now with a live web view and Linear sync.

tbd (short for “To Be Done,” or “TypeScript beads” if you prefer) combines five 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.
5. Live views and tracker sync: A local web interface for browsing beads as they change (tbd web) and synchronization with external trackers, starting with Linear. Beads stay git-native, but the work is visible to your whole team. These are the newest parts of tbd, but they work end to end. (GitHub Issues is planned.)

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 adds .tbd/, installs the portable and Claude skill mirrors, and configures Claude/Codex project hooks). Then it uses 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?”

Two requests worth trying early:

• “Show my beads in a browser”—the agent runs tbd web --open and keeps the live, read-only viewer running while you work.
• “Set up Linear”—the agent walks through connecting the repository to your Linear team, including creating your personal API key (see Optional Linear Setup).

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. Newer releases add live visibility and coordination on top of that layer:

• A live web view: tbd web --open serves a read-only browser view of your beads that updates as agents work. Ask an agent to “show my beads in a browser” and watch statuses, epics, and dependencies change live instead of asking for status updates.
• Bead watching: tbd watch blocks until selected bead state changes on the remote, so unattended workers wake when work arrives—no daemon, no hand-rolled polling loops.
• External tracker sync: tbd integration sync mirrors and synchronizes beads with Linear, so teammates and stakeholders who never touch a CLI stay in the loop.

The web view and Linear sync complete the picture: agents and humans share one durable, git-native task layer, visible from the terminal, the browser, and your tracker.

On multi-agent style: unstructured agent loops like Gas Town and Ralph Wiggum seem great for rapid prototyping, but so far, for 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, simple commands that agents understand. Installs itself as a skill in Claude Code.
• Markdown and YAML frontmatter: One file per bead, human-readable and editable. This eliminates most merge conflicts.
• Live web view (new): tbd web serves a loopback-only, read-only browser view that shares the CLI’s filters and stays current as local bead state changes. It is a viewer, not an editor: ask your agent to change beads with ordinary tbd commands, and the open page updates automatically. It never contacts a remote; explicit tbd sync remains the exchange step.
• External tracker sync (new): tbd integration mirrors selected beads outward to Linear for visibility, or synchronizes them bidirectionally under a per-repository policy. GitHub Issues is planned.
• Agent watching: tbd watch blocks until selected bead state changes on the remote, reports the change, and exits—wake unattended agents with no daemon and no polling loops.
• 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: 25+ 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 terrible or excellent, 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 25+ 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 documentation style.

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

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

Requirements:

• Node.js 22.12.0 or newer
• Git 2.42+ (for orphan worktree support)

npm install -g get-tbd@latest

# Fresh project (--prefix is REQUIRED—a short alphabetic name used as an issue ID prefix, e.g. myapp → issues like 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.

Upgrading an existing installation is the same two commands, run by you or your agent:

npm install -g get-tbd@latest   # Upgrade the CLI
tbd setup --auto                # Refresh skills/hooks and apply any format migration

If the new version bumps the repository format (tbd_format in .tbd/config.yml), setup migrates it automatically and prints a notice; commit the resulting diff to publish the upgrade to your team. Teammates still on an older tbd then see “This repository requires a newer version of tbd” until they run the same two commands. Issue data is never touched by an upgrade, and the migration is revertible: see “Aborting a Format Upgrade” under Troubleshooting in the CLI manual (tbd docs manual). If you have forked docs in docs/tbd/, tbd sync prints a notice when their upstream versions moved; run tbd docs update to merge the changes in.

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=proj   # Short alphabetic prefix for issue IDs
git add .tbd/ .agents/ .claude/ .codex/ AGENTS.md
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 works without an external tracker. Linear synchronization is one of the newest parts of tbd, but it works end to end: mirror selected beads outward for visibility, or synchronize bidirectionally so edits and comments flow both ways.

To add Linear, say “Set up Linear.” The agent runs tbd shortcut setup-linear, which first determines whether this is a first-time repository setup or a teammate joining a repository whose configuration is already committed.

The distinction is intentional: .tbd/config.yml holds the shared Linear team, project, and policy, while every contributor supplies their own LINEAR_API_KEY through their environment or a gitignored .env. A joiner should not edit the shared target or start with an outbound-only push; the walkthrough verifies their key, previews the reconciliation, and then uses plain tbd sync so current team bead state is pulled first. Create personal keys under Linear’s Settings > Account > Security & Access, and never paste a raw key into chat or commit it.

The default policy mirrors the shape of the work rather than every bead: open epics plus anything with a live plan spec, typically around 10% of a repository. Once configured, tbd integration status verifies the connection, and plain tbd sync covers Linear along with docs and issues, so a session-end sync keeps everything current. See External Tracker Integrations in the CLI reference for policies, selectors, and bulk-change safety.

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 close proj-a7k2 proj-b3m9 --reason="Sprint done"  # Bulk close (one call, no loops)
tbd sync                       # Sync with remote (auto-commits and pushes)
tbd web --open                 # Open the live, read-only browser viewer
tbd web ../another-repo --open # View another initialized repository
tbd watch --ready --json       # Block until a bead newly becomes ready
tbd watch --bead proj-a7k2     # Block until one bead changes on the remote
tbd changes --since <commit>   # What changed since a sync-branch commit

tbd watch wakes an agent when bead state changes, with no daemon and no background process. It polls the remote sync-branch tip, fetches only once that tip moves, reports one matching change, and exits. It writes no shared state, so watchers coexist with ordinary tbd sync in the same checkout. The CLI reference documents the selectors, baseline commits, and report format; the watch-beads shortcut has the unattended worker loop and the Claude Code and Codex recipes.

tbd web stays in the foreground and serves the same bead queries and hierarchy as the CLI in a live local board, with filters and facet counts, column sorting, an expandable hierarchy view, and the equivalent CLI command for the current view. It binds loopback only, has no write route, and does not open a browser unless you pass --open. An optional path (tbd web ../another-repo --open) serves any initialized repository from elsewhere. When you ask an agent to show your beads in a browser, the agent should run tbd web --open, wait for the URL, give it to you, and keep the process running. The page is a viewer, not an editor: its controls only change the view, so ask the agent to create, update, close, label, or sync beads with ordinary tbd commands, and their local results appear on the open page automatically. It never fetches from the remote on its own; run tbd sync and the resulting local changes appear without a browser refresh. See the CLI reference for ports, JSON and dry-run options, and full details of the board’s behavior.

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 integration status                 # Verify config, credential, and connectivity
tbd --dry-run integration sync         # Preview the full reconciliation, write nothing
tbd integration sync                   # Both directions: reconcile every linked pair
tbd integration sync --push            # Outbound only: project beads to the tracker
tbd integration link proj-a7k2 FIN-123 # Bind a bead to an existing issue
tbd integration unlink proj-a7k2       # Sever the link; nothing is deleted anywhere

Once an integration is enabled, plain tbd sync includes it, so most sessions never need these commands directly. See External Tracker Integrations in the CLI reference for policies, selectors, and bulk-change safety.

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
# (per-kind aliases for `tbd docs add <docref>`)
tbd guidelines --add=<url> --name=<name>
tbd shortcut --add=<url> --name=<name>
tbd template --add=<url> --name=<name>

Forkable: see them in your repo. By default these docs are served from a hidden, gitignored cache. Fork any of them into docs/tbd/ and they become visible on GitHub, reviewable in PRs, and editable in place—tbd serves your copy instead, and tbd docs update merges upstream improvements into it after an upgrade:

tbd docs fork --all              # Or fork by name: tbd docs fork <name> [<name>...]

Available shortcuts:

Available guidelines: See Built-in Engineering Knowledge for the full list of 25+ 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                     # Managed-docs overview (cached, forked, and local docs)
tbd docs show tbd-docs       # Full CLI reference (the manual; alias: tbd docs manual)

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—and builds coordination on top of it: tbd watch wakes agents when bead state changes, tbd web shows the board live, and tbd integration sync keeps an external tracker current. Sub-second messaging and atomic claims are a separate problem; tools like Agent Mail and Gas Town address that space and are complementary to tbd. See the design doc for a detailed comparison.

Yes, two ways, both newer additions:

• tbd web --open serves a live, read-only board of your beads in a local browser—the fastest way to watch agents’ progress.
• The Linear integration mirrors or fully synchronizes selected beads with your team’s tracker, so people who never clone the repo still see (and can update) the work. See Optional Linear Setup.

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 25+ 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