tbd

tbd is a skill and CLI that upgrades coding quality, task tracking, and workflows for any coding agent.

It gives agents git-native task tracking for longer unattended work (beads), reusable engineering guidelines, and reusable workflows (code reviews, PR workflows, shortcuts). Adoption is gradual (use only what you want), customizable (override or replace skills and guidelines), and batteries included (the defaults encode hard-learned practices).

tbd (short for “To Be Done,” or “TypeScript beads” if you prefer) started in January 2026 as a better Beads (bd) and has since added workflows of many kinds. Beads are Markdown files on a dedicated sync branch, so agents and humans share one durable task layer across sessions and machines, with no daemon and no database. It installs as a skill for Claude Code and Codex, works through the CLI in any other agent environment, and is a drop-in replacement for bd.

1. Beads: Git-native issue tracking (tasks, bugs, features). Never lose work across sessions. Drop-in replacement for bd.
2. Spec-Driven Workflows: Plan features → break into beads → implement systematically.
3. Knowledge Injection: 40+ engineering guidelines (TypeScript, Python, Rust, TDD, testing, Convex, monorepos) available on demand.
4. Shortcuts: Reusable instruction templates for common workflows (code review, commits, PRs, cleanup, handoffs).

On top of that, tbd web shows beads live in a browser, tbd watch wakes agents when bead state changes, tbd integration syncs beads with Linear, and policy grants record which actions agents may take in the project (see Features at a Glance).

Install the CLI:

npm install -g get-tbd@latest

Then tell your agent:

“Run tbd prime, then set up tbd in this project.”

The agent asks you for a short issue-ID prefix, runs tbd setup --auto --prefix=<name>, and follows tbd shortcut setup-tbd, which asks you once, for the project as a whole, which policy grants agents have here (GitHub editing and merging, stacked PRs, sub-agents, PR review requirements, and Linear sync) and records the answers in AGENTS.md. Unanswered grants stay ask-first; “not now” is a valid answer. Merge, stacks, sub-agents, and Linear can be granted later. Say “Set up tbd” again after any upgrade: it asks only about policies that are still unanswered. From then on you talk to your agent in natural language; “what can I do with tbd?” runs the welcome shortcut. For cloud instances and upgrades, see Installation and Setup.

The agent translates your requests into tbd commands: some do things, like creating beads, and others give the agent context, knowledge, or a workflow to follow. These are the requests the installed skill routes; say them in your own words.

Every default in a shortcut yields to your specific guidance: “post the review as a PR comment”, “also do a security review”, “two rounds”, or “don’t merge anything today”.

• Git-native beads: one Markdown file with YAML frontmatter per bead, on a dedicated tbd-sync branch, so parallel creation never conflicts and your code history stays clean; JSON output, bulk commands, and self-documenting help keep it agent-operated.
• Spec-driven workflows: shortcuts for the full cycle: plan spec, beads, implementation, validation plan, and PR.
• PR review lifecycle: reviews published at a pinned head under one review-state contract, addressed finding by finding, with a merge gate before any merge (see pr-review-workflows).
• Policy grants and delegation: standing, project-wide consent for classes of agent actions, recorded in AGENTS.md and managed with tbd policy, plus one delegation procedure for any platform with provider-neutral model tiers (see Agent Policies and Delegation).
• Live web view and watching: tbd web --open serves a loopback-only, read-only board that updates as beads change, and tbd watch blocks until selected bead state changes on the remote, with no daemon (see Commands).
• Linear sync: tbd integration mirrors or synchronizes selected beads with Linear, and plain tbd sync covers it (see Optional Linear Setup).
• Guidelines, shortcuts, and templates: bundled docs the agent loads by name, forkable into docs/tbd/ and extensible from any URL (see Shortcuts, Guidelines, and Templates).
• Beads compatible: largely compatible with bd at the CLI level, with tbd setup --from-beads to migrate (see Why tbd).

Requirements:

• Node.js 22.12.0 or newer
• Git 2.42 or newer (orphan worktree support)
• GitHub CLI (gh) 2.97.0 or newer, optional: the generated session hook installs it when missing or too old; pass --no-gh-cli to setup, or set use_gh_cli: false under settings: in .tbd/config.yml, to leave gh alone.

npm install -g get-tbd@latest   # Install or upgrade (same command for both)

On a fresh cloud instance (such as Claude Code Cloud) where the CLI is not installed, tell the agent: “install tbd (npm install -g get-tbd@latest), run tbd prime, and set up tbd in this project.”

tbd setup --auto --prefix=myapp   # Fresh project (--prefix is REQUIRED: a short alphabetic name used in issue IDs, e.g. myapp → myapp-a1b2)
tbd setup --auto                  # Existing tbd project; also the upgrade step after npm install -g
tbd setup --from-beads            # Migrate from Beads (see Migrating from Beads)

tbd setup --auto is idempotent and safe to run at any time: it initializes .tbd/, refreshes the cached docs and every agent surface, applies any repository format migration, and writes the policy block in AGENTS.md back unchanged. Commit the diff it reports. Bare tbd setup displays help. The setup-tbd shortcut wraps these commands: it installs or upgrades the CLI, runs setup, asks about unanswered policy grants and records the answers, sets up gh authentication, stack tooling, and Linear as the grants require, and verifies with tbd doctor. The output of a fresh setup points to it; run it (say “Set up tbd”) for a new project and after every upgrade.

Upgrading is the same two commands, npm install -g get-tbd@latest and tbd setup --auto. If the new version bumps the repository format (tbd_format in .tbd/config.yml), setup migrates it and prints a notice; commit the diff, and teammates on an older tbd see “This repository requires a newer version of tbd” until they upgrade too. Issue data is never touched, and the migration is revertible (see “Aborting a Format Upgrade” in the CLI manual, tbd docs manual).

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 the committed config

Policy grants are committed with AGENTS.md, so joiners inherit them.

Setup installs six project-local surfaces by default. --surfaces=<comma-list> (or all) narrows the generated files; it does not skip initialization, migration, or the docs refresh.

Claude Code and Codex get the same hooks: at session start, tbd whoami --ensure-id sets a stable, machine-local agent identity, tbd prime injects workflow context and the effective policy grants, and ensure-gh-cli.sh installs gh unless disabled; a brief tbd prime runs before context compaction and the closing reminder after tool use. Codex also reads AGENTS.md; other agents (Cursor, for example) use the portable skill, AGENTS.md, or just the CLI, since tbd prime gives any agent the full workflow.

The four tier agent definitions (tbd-strong-max, tbd-strong, tbd-moderate, and tbd-fast) each set a model and a reasoning level from the dated suggestions in agent-model-tiers; setup refreshes them on every run, so upgrading tbd updates them, and removing a file’s DO NOT EDIT marker takes it over. To leave them out, list the other surfaces: --surfaces=portable,agents-md,claude,codex.

tbd status lists the installed skill, hooks, and AGENTS.md block, though not the tier agent definitions, which tbd doctor reports once they exist. tbd uninstall --confirm removes .tbd/, the hidden worktree, the local sync branch (unless --keep-branch), and the generated tier agent definitions; the skills, hooks, and the AGENTS.md block stay in place.

The PR shortcuts use gh. Authenticate with gh auth login, or set GH_TOKEN (a Personal Access Token, fine-grained recommended, with Contents and Pull requests read/write permissions) and GH_PROMPT_DISABLED=1 before starting the session: in the project’s environment variables on Claude Code Cloud, or in your shell profile locally. The session hook enforces the gh 2.97.0 floor. Stack tooling (the pinned gh-stack extension and its agent skill) is installed only when the github-stacked-prs policy is granted, through ensure-gh-cli.sh --with-stack as the setup-github-cli shortcut describes; without the grant, agents propose separate PRs instead. Authentication is separate from authorization: a working gh login is not a grant, and a grant never bypasses a tool permission.

tbd works without an external tracker. To add Linear, say “Set up Linear.” The agent runs tbd shortcut setup-linear, which tells first-time repository configuration apart from a teammate joining a repository whose configuration is already committed: .tbd/config.yml holds the shared Linear team, project, and policy, while each contributor supplies a personal LINEAR_API_KEY through the environment or a gitignored .env, never in chat or in a commit. When the linear policy is granted, the default selection is epics: open epic beads, synchronized in both directions. tbd integration status verifies the connection, plain tbd sync then covers Linear, and External Tracker Integrations in the CLI reference has the policies, selectors, and bulk-change safety.

tbd --dry-run setup --from-beads  # Preview; writes nothing
tbd setup --from-beads            # Initialize, import, install surfaces, archive .beads/
tbd stats                         # Verify
tbd list --all

Run this before initializing tbd, while .beads/ still exists. Setup imports .beads/issues.jsonl when present and renames the directory to .beads-disabled/, the rollback source; it can continue after a missing JSONL file or import warning, so verify the totals. It does not remove .beads-hooks/, Cursor rules, Claude settings, or Beads text in AGENTS.md. Issue IDs are preserved: proj-123 in Beads is proj-123 in tbd.

A policy grant records your explicit consent for a class of agent actions, for the project as a whole, so agents neither ask in every session nor act without consent. Grants live in a policy block inside the tbd block in AGENTS.md, are committed like any other change, and take effect from the default branch. The seven policies:

The block, with its fixed prose omitted:

<!-- BEGIN TBD POLICY GRANTS v=1 -->

- `github-workflows`: granted
- `github-editing`: granted
- `github-merge`: confirm-session
- `github-stacked-prs`: granted
- `subagents`: granted
- `pr-review-requirements`: standard
- `linear`: not-granted

Recorded 2026-09-17.
<!-- END TBD POLICY GRANTS -->

tbd policy show                            # Answered and unanswered policies, with effective values
tbd policy grant subagents                 # Record the recommended value
tbd policy revoke github-merge             # Record the revoke value, what an unanswered policy takes
tbd policy set pr-review-requirements standard + 2 rounds   # Record any valid value
tbd policy refresh                         # Rewrite generated guidance only (grants, date, notes untouched)
tbd setup --auto --policies=recommended    # Record the recommended set for every unanswered policy (Linear is asked separately)

An unanswered policy is treated as not-granted, with two exceptions (confirm-every for github-merge and standard for review requirements), and the agent asks when a task needs it. Your instructions in the conversation override recorded grants for that task, in either direction, and a grant never bypasses a tool permission or sandbox. The block interior is fully managed: grant, revoke, and set rebuild everything between the markers from the recorded grants and the date, so text you add by hand in there is lost the next time one of them runs. Only refresh leaves it alone, so keep notes about your grants outside the markers. tbd prime prints the effective grants, tbd doctor validates the block, and agent-policy-grants is the full definition.

Delegation. With subagents granted, agents follow delegate-to-subagents: your session is the coordinator; it splits the work by role (reviewer, addressing agent, administrator), assigns each task a tier from agent-model-tiers (strong, moderate, or fast, defined by model rank and reasoning level within your own provider), spawns fresh, named sub-agents through the generated tbd-* definitions, writes self-contained briefs, and verifies every claim that comes back. review-and-merge-prs runs the reviews, the addressing pass, the round decision, and the merge gate this way; without sub-agents, one session performs the same steps in order. The vendor guidance behind the procedure is in the sub-agent research brief.

tbd ready                      # Open work with no delegate, hold, deferral, or blocker
tbd list                       # List open beads (--all includes closed; --specs groups by spec)
tbd show proj-a7k2             # View bead details (several IDs in one call)
tbd create "Title" --type=bug  # Create bead (bug/feature/task/epic/chore)
tbd start proj-a7k2            # Claim under the resolved agent identity
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 dep add proj-b3m9 proj-a7k2  # b3m9 depends on a7k2
tbd label add proj-a7k2 urgent backend
tbd search "authentication"    # Search beads by text or partial ID
tbd sync                       # Sync with remote (auto-commits and pushes)
tbd web --open                 # Open the live, read-only browser viewer
tbd watch --ready --json       # Block until a bead newly becomes ready
tbd changes --since <commit>   # What changed since a sync-branch commit

tbd start writes the acting agent to delegate and preserves the accountable assignee; tbd whoami shows the identity it records. Pull and re-read shared state before claiming, then sync the accepted claim; the collision check is local and advisory.

tbd web stays in the foreground, binds loopback only, has no write route, and serves the same queries and hierarchy as the CLI. It is a viewer, not an editor: ask the agent to change beads with ordinary commands, and the open page updates automatically; it never fetches from the remote on its own, and tbd web ../another-repo --open serves any initialized repository. tbd watch polls the remote sync-branch tip, fetches only once it moves, reports one matching change, and exits; a --ready watch is edge-triggered, so the watch-beads shortcut adds startup and periodic tbd ready scans for an unattended worker loop. The CLI reference has ports, selectors, and the JSON and dry-run options.

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 directly.

tbd                          # Command help
tbd prime                    # 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)
tbd design                   # Design doc
tbd status                   # Repository status and installed surfaces (works before init too)
tbd stats                    # Bead statistics
tbd doctor                   # Check for problems (--fix repairs them)
tbd policy show              # Agent policy grants (see Agent Policies and Delegation)

Online: the CLI Reference and the Design Doc.

These global flags are accepted by every command, but commands apply only the behavior they implement:

tbd bundles three kinds of documentation your agent loads on demand:

tbd shortcut --list              # List all shortcuts
tbd shortcut new-plan-spec       # Get the plan spec workflow
tbd guidelines --list            # List all guidelines
tbd guidelines typescript-rules  # Get TypeScript rules (several names in one call)
tbd template --list              # List all templates
tbd template plan-spec           # Get a plan spec template
tbd guidelines --add=<url> --name=my-team-rules   # Add your own from any URL (shortcut and template take --add too)

These docs are cached in .tbd/docs/ (gitignored) during setup and refreshed by every tbd setup --auto. Fork any of them into docs/tbd/ with tbd docs fork <name> (or --category=<name> or --all) 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/config.yml configures which docs are available.

Available shortcuts (43):

Available guidelines (46):

Available templates (4):

Agents can be excellent or poor depending on what they are given: without structure and knowledge they forget conventions between sessions, skip testing, and drift from a team’s patterns, and neither pasting rules into prompts nor piling every rule into CLAUDE.md or AGENTS.md scales. Beads (git-native, CLI-based issue tracking) solve the task management part, raising an agent’s capacity for structured work from a handful of ad-hoc to-do items to hundreds of tracked beads with dependencies that persist in git. Task tracking alone does not help with planning or quality, so tbd adds spec-driven workflows to think through what to build before building it, and curated engineering guidelines the agent loads when it needs them. You can then hand an agent a well-defined spec with clear beads and expert knowledge and get back careful, well-structured code, across sessions.

Spec-driven development. For non-trivial features:

1. Plan: write a planning spec (tbd shortcut new-plan-spec)
2. Break down: convert the spec into implementation beads (tbd shortcut plan-implementation-with-beads)
3. Implement: work through the beads (tbd shortcut implement-beads)
4. Validate: write a validation plan and run the tests (tbd shortcut new-validation-plan)
5. Ship: commit and create the PR (tbd shortcut create-or-update-pr-with-validation-plan), then have it reviewed and merged (tbd shortcut review-and-merge-prs)

Iterating on the spec is the hard part; with a good spec, writing the code is often almost automatic. These workflows come from heavy spec-driven agentic coding, and shortcuts make them repeatable, including by voice: “use the shortcut to create a new plan spec that …”.

Compared to Beads. tbd was inspired by Beads by Steve Yegge and keeps the idea with a simpler architecture: plain Markdown files instead of JSONL, no daemon modifying the working tree, no SQLite, no 4-way sync. That avoids merge conflicts, sync confusion across branches and the database, and file locking on network filesystems such as Claude Code Cloud; beads stay in git on the tbd-sync branch, and tbd watch, tbd web, and tbd integration sync build on that layer. The design doc has the detailed comparison.

See Why tbd: the same idea with a simpler architecture. If you already use Beads, tbd setup --from-beads migrates you, preserving every issue ID (see Migrating from Beads).

Yes, two ways: tbd web --open serves a live, read-only board in a local browser, and the Linear integration mirrors or 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).

Only as far as the project allows, and the github-merge policy has four settings rather than yes or no. never means an agent does not merge at all; confirm-every, which is what an unanswered policy means, needs your authorization for each merge, so “Make sure PR #N is reviewed and merged” authorizes that PR and nothing else; confirm-session (recommended) lets it merge once a session confirmation covers the task it was given for: the PRs of the task the user confirmed, including every layer of a stack those merges include, and a PR outside that task needs its own confirmation; autonomous lets it merge without asking. None of them lowers the review bar: pr-review-requirements decides whether a PR is ready, and the merge gate checks it separately in every case. Before merging, review-and-merge-prs checks the merge gate: the review requirements are met (under standard, a senior engineering review at a pinned head, a pass addressing all its findings, and a dedicated review for each area the PR is sensitive in), every finding has a disposition and every deferral an open bead, no newer review content is unaddressed, any question about another round has been answered, CI is green at the unchanged head, GitHub reports the PR mergeable, and every layer below a stack layer has merged. The merge uses the repository’s merge method at the gated head, never --admin, and a branch-protection block is reported, not bypassed.

Yes. Add your team’s docs from any URL with tbd guidelines --add (and tbd shortcut --add or tbd template --add), fork the bundled ones into docs/tbd/ to edit them in place, and configure which docs are available in .tbd/config.yml (see Shortcuts, Guidelines, and Templates).

Yes. It was bootstrapped with the original bd, imported its own issues, and has tracked its own specs and beads and loaded its own guidelines since; all of its code and specs are agent-written.

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

MIT