Spawn and coordinate parallel Claude Code sub-agents using git worktrees. Use this skill when you need to parallelize work across multiple independent tasks, delegate subtasks to sub-agents, or orchestrate complex multi-part implementations.
Use GitterFlow to spawn sub-agents that work in parallel on independent tasks. Each sub-agent runs in an isolated git worktree and automatically merges back when complete.
Use GitterFlow when you have:
Do NOT use GitterFlow for:
gf new --task "Detailed task description" --autonomous
This creates a new worktree, spawns Claude Code with the task, and automatically merges when complete.
Example:
gf new --task "Implement shell completions for bash, zsh, and fish" --autonomous
gf new --task "Add retry logic with exponential backoff to API client" --autonomous
gf new --task "Write comprehensive unit tests for the auth module" --autonomous
gf status
Shows all running, completed, and failed sub-agents.
gf new feature-branch --task "Add new feature"
Creates worktree and starts Claude, but requires manual gf finish when done.
gf finish when Claude exitsWrite clear, self-contained task descriptions:
Good:
gf new --task "Add a --verbose flag to all CLI commands. The flag should:
1. Enable detailed logging of git operations
2. Show timing information for each step
3. Be configurable via GITTERFLOW_VERBOSE env var
Include tests for the new functionality." --autonomous
Bad:
gf new --task "Add verbose mode" --autonomous # Too vague
When orchestrating multiple sub-agents:
# 1. Spawn all sub-agents at once
gf new --task "Implement feature A with tests" --autonomous
gf new --task "Implement feature B with tests" --autonomous
gf new --task "Update documentation for A and B" --autonomous
# 2. Monitor progress
gf status
# 3. Handle any failures
# Failed agents have status: failed
# Inspect worktree: cd ../branch-name
# Fix issues and run: gf finish
If a sub-agent completes but has merge conflicts:
conflict statecd ../branch-namegf finish to complete the mergeIf you are a sub-agent spawned by GitterFlow, run gf ready when your task is complete:
gf ready
This command:
IMPORTANT - Do NOT use gf finish! The brain agent will handle merging.
gf ready instead of gf finish?You can't see what other sub-agents are doing. If you try to merge directly:
The brain agent coordinates all merges because it has full visibility into all agents' work.
gf ready:readygf statusWhen you are the orchestrating "brain" agent coordinating sub-agents:
gf status
Look for agents with ready status - these have completed their work and are awaiting merge.
For each ready branch, go to the base branch directory and merge:
# In the main repo (not a worktree)
git checkout main
git pull origin main
git merge <branch-name>
If merge succeeds, the agent's work is now in the base branch.
If a merge conflicts:
git add . && git commitAfter successful merge, update the agent's status:
# This will be automated in future versions
# For now, the worktree can be cleaned up manually:
git worktree remove <worktree-path>
git branch -d <branch-name>
Note: This feature is in design phase. See
docs/PLAN-APPROVAL-DESIGN.md.
Plan mode enables a two-phase workflow where subagents write an implementation plan before executing. The brain agent reviews and approves/rejects plans before any code is written.
# Spawn subagent in plan-first mode
gf new --task "Implement feature X" --plan-first --autonomous
This will:
--permission-mode plan (read-only)awaiting_approval and exitsgf approve or gf rejectWhen subagents are in awaiting_approval status:
gf status shows agents awaiting approval.gitterflow/agents/{branch}/plan.mdgf approve <branch> - Plan is good, start executiongf reject <branch> --message "feedback" - Needs revisionIf you were spawned with --plan-first, you are in plan mode:
.gitterflow/agents/{your-branch}/plan.mdgf status --write "awaiting_approval"Plan file format:
# Implementation Plan: {task summary}
## Analysis
- Examined files: [list]
- Key findings: [summary]
## Approach
1. Step one
2. Step two
## Files to Modify
| File | Changes |
|------|---------|
| src/foo.ts | Add new function |
## Files to Create
- src/new-feature.ts - Main implementation
## Risks and Considerations
- Risk 1: mitigation
## Questions for Brain (if any)
- Should we use approach A or B?
# Approve a plan and start execution phase
gf approve <branch>
gf approve <branch> --message "Looks good, proceed"
# Reject a plan with feedback
gf reject <branch> --message "Use exponential backoff instead"
For server-side orchestrators (like Clawdbot) or CI pipelines where terminal spawning isn't available, use --headless:
# Returns JSON instead of spawning terminal
gf new --task "Implement feature" --autonomous --headless
Output:
{
"success": true,
"branch": "worktree-calm-fox-123",
"worktree": "/path/to/worktree",
"baseBranch": "main",
"task": "Implement feature",
"autonomous": true,
"planFirst": false,
"agentCommand": "claude --permission-mode acceptEdits \"Implement feature\""
}
Use this to:
The agentCommand field shows the exact command that would be run, so you can execute it programmatically.
For programmatic execution without terminals, use Claude Code's -p (print/SDK) mode:
# Run Claude Code headlessly in a worktree
cd /path/to/worktree && claude -p "Your task description" \
--allowedTools "Read,Edit,Bash,Grep,Glob" \
--append-system-prompt "When done, run: gf finish"
Key flags:
-p "prompt" - Non-interactive/headless mode--allowedTools - Auto-approve specific tools (no prompts)--append-system-prompt - Add instructions to system prompt--output-format json - Get structured output with session ID--continue - Continue most recent conversation--resume <id> - Resume specific sessionExample: Full headless workflow:
# 1. Create worktree
result=$(gf new --task "Add retry logic" --autonomous --headless)
worktree=$(echo $result | jq -r '.worktree')
# 2. Run Claude Code headlessly
cd $worktree && claude -p "Implement retry logic with exponential backoff" \
--allowedTools "Read,Edit,Write,Bash,Grep,Glob" \
--output-format json
# 3. Finish and merge
gf finish
Claude Code supports native subagents that can be used alongside GitterFlow:
# Define subagents dynamically via CLI
claude --agents '{
"implementer": {
"description": "Implements features based on specs",
"prompt": "You implement features. Focus on clean code and tests.",
"tools": ["Read", "Edit", "Bash"],
"model": "sonnet"
}
}'
When to use GitterFlow vs Claude Code subagents:
| Use Case | GitterFlow | Claude Code Subagents |
|---|---|---|
| Isolated git branches | ✅ | ❌ |
| Parallel merges | ✅ | ❌ |
| Same-context subtasks | ❌ | ✅ |
| Read-only exploration | ❌ | ✅ (Explore agent) |
| Multi-model delegation | ❌ | ✅ (Haiku for fast tasks) |
Combine them: Use GitterFlow for branch isolation, Claude Code subagents for in-worktree task delegation.
gf status to track progress of all agentsgf ready