todo-branch — Claude Code command: what it does, how to install
todo-branch executes backlog items on your active Git branch through guided phases, step-by-step approvals, and a single final commit.
no license ★ 1,357 updated 2026-03-01
.claude/commands/todo-branch.mdWhat todo-branch does
This command converts items from todos/todos.md into functional code without switching branches or setting up git worktrees. The lifecycle follows five sequential phases: initialization, selection, codebase exploration, implementation, and commit. The assistant pauses at designated checkpoints, requiring explicit confirmation before proceeding.
Under the hood, parallel sub-agents inspect the codebase to map build scripts, entry points, and test frameworks into todos/project-description.md. When you pick a task, it generates an isolated directory inside todos/work/ containing an architecture analysis and an actionable checklist.
The process relies on a Git repository and local markdown files. Every file change gets staged as tasks finish, culminating in one unified Git commit that bundles your code updates with updated task logs.
What it helps with
- Convert rough items in
todos/todos.mdinto verified features - Recover abandoned implementation sessions using background process checks
- Enforce step-by-step manual sign-off before modifying code
- Keep branch history clean by bundling task notes and code into one commit
Example prompts for the agent
- /todo-branch
- Run /todo-branch to pick up the next task from the backlog
- Check for unfinished tasks using /todo-branch
How to install todo-branch
Manually: put the files in place
.claude/commands/todo-branch.mdCall it with /todo-branch. For all projects use ~/.claude/commands/
Manually: put the files in place
~/.codex/prompts/todo-branch.mdCall it with /prompts:todo-branch. Codex marks this format deprecated in favour of skills
Manually: put the files in place
.github/prompts/todo-branch.prompt.mdManually: put the files in place
.gemini/commands/todo-branch.tomlGemini stores commands as TOML: the prompt text goes into the prompt field
Questions about todo-branch
How to install todo-branch in Claude Code?
Place the command definition file into .claude/commands/todo-branch.md within your project repository.
Does todo-branch require git worktrees?
No, it deliberately works directly on your current branch and bundles all changes into a single commit at the end.
How does the command handle interrupted runs?
It inspects task folders inside todos/work/, checks whether the recorded process ID is still alive, and lets you resume from the exact phase where it stopped.