# todo-worktree

todo-worktree takes tasks from a todo list and implements them inside isolated git worktrees with strict phased approvals.

- command · `type=command` · Claude Code, Codex, GitHub Copilot, Gemini CLI · ★ 1357 repo stars
- Author: qdhenry
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/qdhenry/Claude-Command-Suite/tree/HEAD/.claude/commands/project/todo-worktree.md
- Updated: 2026-03-01
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/commands/todo-worktree

## What it 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.

## Install

### Claude Code (native platform)

**Manually: put the files in place**
- File: `.claude/commands/todo-worktree.md` — Call it with /todo-worktree. For all projects use ~/.claude/commands/

### Codex

**Manually: put the files in place**
- File: `~/.codex/prompts/todo-worktree.md` — Call it with /prompts:todo-worktree. Codex marks this format deprecated in favour of skills

### GitHub Copilot

**Manually: put the files in place**
- File: `.github/prompts/todo-worktree.prompt.md`

### Gemini CLI

**Manually: put the files in place**
- File: `.gemini/commands/todo-worktree.toml` — Gemini stores commands as TOML: the prompt text goes into the prompt field

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/qdhenry/Claude-Command-Suite/tree/HEAD/.claude/commands/project/todo-worktree.md

## When to use it
- 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
- Pick the next task from todos and set up a worktree
- Resume the orphaned task from the worktree list
- Run `/todo-worktree` to plan and execute the selected feature

## Similar
- [ce-worktree](https://affpapa.org/en/nevibecode/skills/ce-worktree.md) — skill · 3200 installs
- [git-worktree-isolation](https://affpapa.org/en/nevibecode/skills/git-worktree-isolation.md) — skill · 2300 installs
- [worktree-deliver](https://affpapa.org/en/nevibecode/commands/worktree-deliver.md) — command · 81 installs
- [git-worktree-manager](https://affpapa.org/en/nevibecode/skills/git-worktree-manager.md) — skill · 581 installs
- [todo](https://affpapa.org/en/nevibecode/commands/todo.md) — command · 2723 installs
- [om-auto-create-pr](https://affpapa.org/en/nevibecode/skills/om-auto-create-pr.md) — skill · 4700 installs

From the same set: [qdhenry/claude-command-suite](https://affpapa.org/en/nevibecode/by/qdhenry/claude-command-suite.md) — 112 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
