todo-worktree — Claude Code command: what it does, how to install
todo-worktree takes tasks from a todo list and implements them inside isolated git worktrees with strict phased approvals.
no license ★ 1,357 updated 2026-03-01
.claude/commands/todo-worktree.mdWhat todo-worktree does
The command guides an agent through a strict five-step pipeline: INIT, SELECT, REFINE, IMPLEMENT, and COMMIT. Instead of editing your main working copy directly, it spins up a dedicated git worktree with a timestamped branch for each task chosen from todos/todos.md.
Before touching application code, sub-agents inspect the repository to map commands, test configurations, and architecture into todos/project-description.md. Every checkbox in the implementation plan requires direct user sign-off, and the agent commits progress after completing each item.
Interrupted work will not be lost. The workflow logs the agent PID inside task.md and detects abandoned worktrees on restart. You will need an editor launch command such as code or cursor to open isolated task folders.
What it helps with
- isolate new features in dedicated git worktrees
- generate step-by-step implementation plans from raw todos
- resume abandoned tasks using recorded agent PIDs
- run validation checks before final task commits
Example prompts for the agent
- Pick the next task from todos and set up a worktree
- Resume the orphaned task from the worktree list
- Run
/todo-worktreeto plan and execute the selected feature
How to install todo-worktree
Manually: put the files in place
.claude/commands/todo-worktree.mdCall it with /todo-worktree. For all projects use ~/.claude/commands/
Manually: put the files in place
~/.codex/prompts/todo-worktree.mdCall it with /prompts:todo-worktree. Codex marks this format deprecated in favour of skills
Manually: put the files in place
.github/prompts/todo-worktree.prompt.mdManually: put the files in place
.gemini/commands/todo-worktree.tomlGemini stores commands as TOML: the prompt text goes into the prompt field
Questions about todo-worktree
How to install todo-worktree in Claude Code?
Save the command definition file to .claude/commands/todo-worktree.md.
What does todo-worktree do?
It selects an item from todos/todos.md, moves it to an isolated git worktree, and walks through planning, implementation, and commit phases with explicit user confirmation.
How does todo-worktree track interrupted tasks?
It writes the agent PID into task.md inside the worktree directory. During initialization, it scans those files against running system processes to find unfinished sessions.