Gitterflow

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

Check Status

gf status

Shows all running, completed, and failed sub-agents.

Manual Worktree (Non-Autonomous)

gf new feature-branch --task "Add new feature"

Creates worktree and starts Claude, but requires manual gf finish when done.

How It Works

1. Isolation: Each sub-agent gets its own git worktree (separate directory)
2. Pre-trusted: Worktrees are automatically trusted (no permission dialogs)
3. Auto-merge: Autonomous agents run gf finish when Claude exits
4. Failure handling: Failed agents leave worktree intact for inspection

Task Description Best Practices

Write 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

Parallel Execution Pattern

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

Handling Merge Conflicts

If a sub-agent completes but has merge conflicts:

1. Status shows conflict state
2. Navigate to the worktree: cd ../branch-name
3. Resolve conflicts manually
4. Run gf finish to complete the merge

For Sub-Agents: Completing Your Task

If you are a sub-agent spawned by GitterFlow, run gf ready when your task is complete:

gf ready

This command:

1. Auto-commits any uncommitted changes with an AI-generated message
2. Marks your work as ready for the brain to merge
3. Exits successfully - you're done!

IMPORTANT - Do NOT use gf finish! The brain agent will handle merging.

Why gf ready instead of gf finish?

You can't see what other sub-agents are doing. If you try to merge directly:

• You might conflict with another agent's recent merge
• You lack context to resolve conflicts correctly
• You could corrupt the base branch for everyone

The brain agent coordinates all merges because it has full visibility into all agents' work.

After running gf ready:

• Your status changes to ready
• The brain sees you're ready via gf status
• The brain merges your work at the right time
• The brain handles any conflicts with full context

For Brain Agents: Merging Sub-Agent Work

When you are the orchestrating "brain" agent coordinating sub-agents:

1. Monitor Progress

gf status

Look for agents with ready status - these have completed their work and are awaiting merge.

2. Merge Ready Branches

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.

3. Handle Conflicts

If a merge conflicts:

1. You're left in the base branch with conflict markers
2. Review both sides - you have context from ALL agents
3. Resolve based on your understanding of the full picture
4. Complete the merge: git add . && git commit

4. Merge Order Considerations

• Independent features: any order works
• Overlapping changes: merge simpler/foundation changes first
• If unsure, review diffs before deciding order

5. Update Agent Status (Future Enhancement)

After 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>

Plan Mode (Plan-Then-Execute Workflow)

Note: This feature is in design phase. See docs/PLAN-APPROVAL-DESIGN.md.

Overview

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.

For Brain Agents: Spawning with Plan Mode

# Spawn subagent in plan-first mode
gf new --task "Implement feature X" --plan-first --autonomous

This will:

1. Start the subagent with --permission-mode plan (read-only)
2. Subagent analyzes codebase and writes plan
3. Subagent sets status to awaiting_approval and exits
4. Brain reviews plan and runs gf approve or gf reject

For Brain Agents: Plan Review Protocol

When subagents are in awaiting_approval status:

1. Check status: gf status shows agents awaiting approval
2. Read plan: Plan is at .gitterflow/agents/{branch}/plan.md
3. Evaluate:
   • Does the approach align with overall architecture?
   • Are there conflicts with other agents' plans?
   • Is the scope appropriate?
4. Decide:
   • gf approve <branch> - Plan is good, start execution
   • gf reject <branch> --message "feedback" - Needs revision

For Sub-Agents: Plan Mode Instructions

If you were spawned with --plan-first, you are in plan mode:

1. Analyze only - You have read-only access (Read, Glob, Grep, WebSearch)
2. Write your plan to: .gitterflow/agents/{your-branch}/plan.md
3. Update status: Run gf status --write "awaiting_approval"
4. Exit - Do NOT implement anything yet

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?

Plan Approval Commands (Placeholder)

# 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"

Headless Mode (CI/Server/Orchestrators)

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:

• Parse worktree path and run your own agent process
• Integrate with session-based orchestrators (Clawdbot sessions_spawn)
• Build CI/CD pipelines that spawn parallel agents
• Create custom automation workflows

The agentCommand field shows the exact command that would be run, so you can execute it programmatically.

Claude Code CLI Integration

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 session

Example: 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

Subagent Patterns from Claude Code Docs

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:

Combine them: Use GitterFlow for branch isolation, Claude Code subagents for in-worktree task delegation.

Important Notes

• Sub-agents merge to your current branch (the branch you were on when spawning)
• Each sub-agent is completely independent - they cannot communicate with each other
• Monitor gf status to track progress of all agents
• Keep tasks independent to avoid merge conflicts
• Brain agents should handle ALL merges - sub-agents should only use gf ready
• Plan mode prevents wasted work by validating approach before implementation
• Headless mode enables server-side orchestration without terminals