tbd
tbd is a skill and CLI that upgrades coding quality, task tracking, and workflows for
any coding agent.
Give your agent durable task memory, engineering guidelines it can load when needed, and
repeatable workflows for planning, reviewing, and shipping changes.
Start with the parts you need.
The defaults are ready to use, and you can customize or replace them with your team’s
practices.
- Beads: Git-native issue tracking for tasks, bugs, and features, shared across
agents, sessions, and machines.
- Spec-Driven Workflows: Plan features, break them into beads, and implement them
systematically.
- Knowledge Injection: Engineering guidelines for languages, testing, architecture,
and other topics, loaded on demand.
- Shortcuts: Reusable instructions for code review, commits, PRs, cleanup, and
handoffs.
These capabilities work together, but you can use beads alone or choose individual
guidelines and workflows.
tbd stores beads as Markdown files on a dedicated Git branch, with no required daemon
or database. It installs project skills and hooks for Claude Code and Codex and works
through the CLI in other agent environments.
Coordinate across agents and sessions. Tasks, plans, specs, and progress are
recorded in the Git repository, not tied to a Claude Code or Codex account or to local
or cloud app state.
Sessions from either tool can use the shared repository to coordinate
on the same beads and plans or hand off ongoing work, following the project’s workflow
instructions.
Quick Start · Adoption Choices ·
Setup · CLI Reference ·
Bundled Library
Quick Start
Requires Node.js 22.12.0 or newer and Git 2.42 or newer.
Install the CLI:
npm install -g get-tbd@latest
Then, with your agent working in your project’s Git repository, tell it:
“Run tbd prime, then set up tbd in this project.”
Or ask the agent to handle both steps:
“Run npm install -g get-tbd@latest, then run tbd prime and set up tbd in this
project.”
Installing the CLI does not initialize the project.
tbd prime gives the agent instructions.
For a new project, the agent asks you for a short issue-ID prefix and runs
tbd setup --auto --prefix=<prefix>. For an existing tbd project, the agent runs
tbd setup --auto without a new prefix.
After initialization, the agent can run
tbd shortcut setup-tbd to review
policy choices and verify setup.
The shortcut is available only inside an initialized tbd repository.
Default setup writes the project’s tbd configuration, agent skills, hooks, and sub-agent
definitions. Review and commit those files so teammates share the setup.
See Agent Surfaces to select which integrations are installed.
Setup also offers project-wide policy choices for GitHub actions, delegation, reviews,
and Linear. You can say “not now” and decide when a task needs them; setting up tbd
does not require granting merge authority or connecting an external tracker.
Start with a request such as “Track the bug where login fails after a password
reset.” Your agent creates a bead that the next session can find.
Ask “What can I do with tbd?” for an introduction tailored to your project.
Adopt Only What You Want
Choose the parts that help your work; these are not required stages.
- Beads without agent integrations. In a Git repository,
tbd init --prefix=myapp
initializes task tracking without installing agent skills or hooks.
Choose your own short prefix; myapp is an example.
Commit the generated .tbd/ configuration and use the CLI directly or through your
agent. tbd sync exchanges bead state through your Git remote.
You can add agent integrations later with tbd setup --auto.
- Selected agent integrations. Use
--surfaces to choose which files a setup run
installs or refreshes.
For example, tbd setup --auto --surfaces=portable,agents-md installs the portable
skill and AGENTS.md guidance.
This does not uninstall existing surfaces or save a preference: repeat the selection
on later runs; unrestricted setup installs all surfaces.
- Your team’s knowledge. Load the bundled guidelines you need, fork them into your
repository to edit, or add your own docs.
See Guidelines, Shortcuts, and Templates.
- Workflows when they help. Use a planning, review, or release shortcut for the task
at hand. You can adjust its instructions and record standing project permissions later.
A workflow shortcut supplies instructions to the agent; it is not an autonomous
scheduler or an enforcement boundary.
The web viewer and bead watcher work with beads alone.
Linear, formal PR stacks, and sub-agent delegation are additional choices, not
prerequisites.
Talking to Your Agent
Your agent operates tbd on your behalf.
These examples show both small tasks and fuller workflows; the installed skill and
request vocabulary
provide the complete routing.
Your specific instructions take precedence over shortcut defaults: for example, “also do
a security review,” “post it as a PR comment,” or “don’t merge anything today.”
Optional Capabilities
Live viewing and watching
Ask your agent to “Show my beads in a browser.” It starts tbd web --open, gives
you the loopback URL, and keeps the process running.
The page updates as local beads change.
It is read-only: ask the agent to edit beads through ordinary commands.
Opening it never fetches or synchronizes remote data.
tbd watch observes changes on the remote sync branch; tbd changes reports changes
since a sync-branch commit.
For an unattended worker, the
watch-beads shortcut combines
watching with checks for work already ready.
The CLI reference has selectors, timing, and JSON
output.
Agent policies and delegation
Project policy grants record standing consent in AGENTS.md; effective grants come from
the repository’s default branch.
tbd policy show explains the current settings.
Without a grant, the agent asks when an action needs authorization.
Unanswered merge policy means confirm-every; unanswered review requirements mean
standard.
Merge authorization and review requirements are separate: permission to merge does not
waive review or validation.
Your instructions can narrow or authorize actions for the current task, and no policy
bypasses a tool permission or sandbox.
The policy guidelines define the
values; the
review workflow defines
review and merge requirements.
For delegated work, the
delegation shortcut
covers task boundaries, model tiers, evidence, and follow-up.
Default setup provides project-local tier definitions; the current model suggestions
live in Agent Model Tiers.
Optional Linear Setup
Say “Set up Linear.” The agent follows
tbd shortcut setup-linear,
whether it is configuring a repository for the first time or helping a teammate join.
The team, project, and sync policy are shared in .tbd/config.yml; each contributor’s
LINEAR_API_KEY stays in their environment or a gitignored .env, never in a commit or
chat message.
Once enabled, plain tbd sync includes Linear according to the integration
configuration. Teammates can view and update selected work in Linear without using the
CLI. See
External Tracker Integrations
for selection, linking, and synchronization behavior.
Installation and Setup
Existing projects and upgrades
Install or upgrade with npm install -g get-tbd@latest, then ask your agent to “Set
up tbd.” The setup shortcut checks the installed CLI, refreshes the project, and asks
about unanswered policies.
It installs a missing or incompatible CLI and asks before an optional upgrade of a
working installation.
The underlying commands are:
tbd setup --auto --prefix=myapp # New project with default agent integrations
tbd setup --auto # Existing project; refresh after upgrading the CLI
tbd setup --from-beads # Import an uninitialized Beads project (see below)
A prefix is required for a new project; choose a short alphabetic name for issue IDs
such as myapp-a1b2. Bare tbd setup displays help.
Setup refreshes cached docs and selected managed agent files, preserves recorded policy
grants, and applies any repository format migration.
Review and commit the diff it reports.
If a format upgrade requires teammates to upgrade too, setup tells you; the
manual documents compatibility and rollback.
For a fresh cloud environment, ask the agent to install get-tbd, run tbd prime, and
set up the project. The same project configuration can be committed and shared across
local and cloud sessions.
Team setup
The first contributor chooses the prefix and commits .tbd/config.yml and the generated
agent files. Joining contributors install the CLI and run tbd setup --auto in the
cloned repository; they use the existing prefix and recorded project policies.
tbd sync exchanges beads on the dedicated sync branch.
Code and setup files still use your ordinary Git commits and pushes.
People who only need task tracking can use the CLI without installing every agent
integration.
Agent Surfaces
Default setup installs all six project-local surfaces.
Select them with --surfaces=<comma-list>; selection does not skip initialization,
migrations, or docs refresh, and does not remove files installed earlier.
| Surface | Project files | Purpose |
|---|
portable | .agents/skills/tbd/SKILL.md | Portable skill |
agents-md | Managed block in AGENTS.md | Orientation and project policies |
claude | .claude/skills/tbd/SKILL.md, settings, and scripts | Claude Code skill and hooks |
claude-agents | .claude/agents/tbd-*.md | Claude Code tier definitions |
codex | .codex/hooks.json and scripts | Codex hooks |
codex-agents | .codex/agents/tbd-*.toml | Codex tier definitions |
Hooks restore context and session identity and remind agents to complete their work.
Other agents can use the portable skill, AGENTS.md, or tbd prime through the CLI.
See setup-tbd for installation
checks.
GitHub tooling
GitHub CLI (gh) is optional for core beads.
The generated session hook can install it when missing or below the required version.
To leave it alone, pass --no-gh-cli to setup or set settings.use_gh_cli: false in
.tbd/config.yml.
For GitHub workflows, the
setup-github-cli shortcut
covers authentication, token permissions, and stack tooling.
A GitHub login is separate from permission to act.
Formal stacks can be authorized for a task or through the project’s standing policy;
existing stacks retain their stack handling.
Migrating from Beads
Import before initializing tbd, while the source .beads/ directory still exists:
tbd --dry-run setup --from-beads # Preview without writing
tbd setup --from-beads # Import and install agent integrations
tbd stats # Check imported totals
tbd list --all
Setup reads .beads/issues.jsonl when present, preserves issue IDs, and renames
.beads/ to .beads-disabled/. Keep that directory as a recovery source and verify the
import: setup can continue after a missing JSONL file or an import warning.
It does not remove unrelated hooks, Cursor rules, Claude settings, or Beads
instructions. See the
migration guide for details.
Shortcuts, Guidelines, and Templates
The bundled library gives your agent instructions and references on demand.
A shortcut is a workflow to follow, a guideline is knowledge to apply, and a template is
a starting point for a document.
You can use them independently of bead tracking.
tbd shortcut --list
tbd guidelines --list
tbd template --list
tbd guidelines typescript-rules
tbd shortcut new-plan-spec
tbd template plan-spec
To customize the library, ask your agent to:
- Load only what the task needs. Select relevant topics instead of putting the whole
library into every prompt.
- Fork a bundled doc.
tbd docs fork typescript-rules creates a tracked, editable
copy in docs/tbd/. tbd serves that copy; tbd docs update merges upstream changes
after upgrades.
- Add team docs.
tbd guidelines --add=<url> --name=my-team-rules registers a URL;
shortcuts and templates support the same flags.
Repository-local docs and overrides can also be configured in .tbd/config.yml.
The .tbd/docs/ cache is disposable; edit a fork or your own source file instead.
The managed-docs guide explains
precedence and update conflicts.
The Bundled Library below is generated from the shipped docs, so its
names, links, and counts stay checked in CI.
Commands
Most users ask their agent to operate tbd.
For direct CLI use:
tbd ready # Find unclaimed, unblocked work
tbd create "Fix login" --type=bug
tbd show myapp-a1b2
tbd start myapp-a1b2 # Claim work under the current agent identity
tbd close myapp-a1b2 --reason="Fixed and verified"
tbd sync # Exchange bead state with the remote
tbd web --open # Live local viewer
tbd status # Repository and installation status
tbd doctor # Diagnose configuration or storage problems
tbd docs # Managed-docs overview
tbd docs show tbd-docs # Full CLI manual
tbd --help
Before claiming shared work, pull and re-read state, then sync your claim.
Claims are advisory, not atomic assignments across machines.
Data-oriented commands support --json; supported mutations accept --dry-run. The
CLI reference has the full commands and flags.
Why tbd
Task state and engineering context solve different problems.
Beads preserve tasks, dependencies, and decisions across sessions; guidelines make
conventions available when an agent needs them; shortcuts make practices such as
planning and review repeatable.
You can adopt each without requiring the others.
They help an agent work systematically, while tests, review, and human judgment still
determine whether a change is good.
For a larger feature, one useful path is spec → implementation beads → implementation →
validation → PR review.
For a small fix, a bead and a focused review may be enough.
Choose the process to fit the work.
tbd (“To Be Done,” or “TypeScript beads”) began in January 2026 as an alternative to
Steve Yegge’s Beads.
It keeps core bd commands and workflows familiar, with Markdown/YAML issue files and
Git-based synchronization.
Compatibility is broad, not an implementation of every bd feature; see the
design comparison.
Capitalized Beads names the original tool; lowercase “beads” means the issues.
Contributing
See docs/development.md for build and test instructions, and
docs/docs-overview.md for the documentation map.
License
MIT
Bundled Library
These catalogs are optional reference material.
Ask your agent to load a named document, or browse with tbd shortcut --list,
tbd guidelines --list, and tbd template --list.
Available shortcuts (43):
Available guidelines (46):
| Group | Guideline | What it covers |
|---|
| General engineering | general-eng-agent-principles | Core principles for AI agents acting as senior engineers |
| Cross-cutting engineering topics | agent-model-tiers | Provider-neutral model tiers for delegated agent work |
| agent-policy-grants | The single definition of the seven agent policies a project can grant (github-workflows, github-editing, github-merge, github-stacked-prs, subagents, pr-review-requirements, linear)—each policy’s values, recommendation, and coverage |
| agent-run-operations-rules | Launching, monitoring, and diagnosing long agent and batch runs |
| backward-compatibility-rules | Guidelines for maintaining backward compatibility only for real consumers and data from released versions |
| ci-and-gates-rules | How to wire a quality gate that actually holds |
| code-review-rules | The language-neutral substance of a code review |
| |
Available templates (4):
| Template | Description |
|---|
architecture-doc | Template for architecture documents |
plan-spec | Template for feature planning specification documents |
qa-playbook | Template for manual testing playbooks and validation workflows |
research-brief | Template for research documents |
