TODO.md was never built for a fleet.
Steering coding agents with TODO files breaks at fleet scale: parallel agents trample each other's work, sessions die and take their context with them, and nothing records what actually happened. tuhdoo replaces the TODO file with a shared backlog, work queue, and activity ledger, stored on a git branch inside the repo it plans. It syncs over the git remote you already have and needs no server, no vendor, and no accounts.
npm i -D tuhdoo && npx tuhdoo initOne repo. One clone. One history.
The backlog and every agent's activity live on the data branch: an orphan git branch inside the repo, with its own history, carrying coordination data instead of code. Clone the repo and the whole plan comes with it; sync is a push and a pull over the remote you already have. There is no server to run, yet the plan is still distributed, version-tracked, and owned by whoever owns the repo.
The agent loop
Agents connect over the Model Context Protocol (MCP) and work one recorded loop: claim, work, escalate, finish. The entire surface is twelve tools, few enough that the whole protocol fits in the single instruction file an agent harness — the tool that runs your agents — loads. Every step lands on the ledger, which is the only continuity between one session and the next.
1Claim
claim_next hands the agent the highest-priority ready task with its description, acceptance criteria, prior notes, and run history. A claim is an exclusive, time-boxed lease; if the agent dies, the task returns to the pool.
2Work
Work happens with ordinary git on ordinary branches; tuhdoo never touches how code is written or merged. Notes on the ledger checkpoint context for whoever picks the task up next.
3Escalate
When a question needs a human, the agent asks and hands off instead of guessing. A blocking escalation holds the task until the question is answered, and the next claimant receives the question and the answer together.
4Finish
Every run ends with a recorded outcome. Reporting done means the acceptance criteria actually hold, and a confirmation gate settles competing claims before anything merges.
Your loop: capture, shape, drain
Capture ideas into the inbox the moment they occur — a title alone is enough, and capturing never drags you into a planning session. Later, work through the pile with an agent and shape captures into real tasks with full descriptions, acceptance criteria, and dependency edges. Then agents drain the ready pool while you watch progress from the tuhdoo TUI (terminal user interface) and answer escalations on your schedule, not the fleet's.
No service attached
Nothing to run
tuhdoo ships as a binary and a git branch; there is no backend service, no subscription, no signup, and no vendor to trust. If you can clone the repo, you hold the entire coordination state, and everything works offline.
One backlog for the team
Everyone who clones the repo sees the same backlog, whatever code branch they have checked out, and every action is attributed to the human behind it. The plan also renders as browsable markdown on your git host.
Leaves no trace
Joining is a clone and one init; leaving is a handful of git commands. tuhdoo installs no hooks, writes nothing into your worktree, and puts no commits on your code branches.
Get started
Install the single static binary from npm, a release archive, or go install. Run tuhdoo init, then connect your agent harness with one MCP config snippet.
Docs: joining a repo, the agent protocol, workflow recipes →