Claude Delegate

Delegate tasks to autonomous Claude Code agents running in tmux. Each delegate gets its own window, reads a task file, produces a result, and signals completion — all without interrupting your main session.

Think of it as a lightweight alternative to Orchestra — one helper at a time instead of a full team.

How it works

You (main Claude Code session)
  │
  ├── /delegate "write tests for auth module"
  │     ↓
  │   Creates task file (.brain/delegates/task-xxx.md)
  │   Spawns new Claude Code in tmux
  │     ↓
  │   Delegate reads task, does the work, writes result
  │   Creates .done signal when finished
  │
  ├── (you keep working on other things)
  │
  └── /delegate-check → shows results

Requirements

# Claude Code CLI
claude --version

# tmux
brew install tmux    # macOS
apt install tmux     # Linux

Install

Option 1: Global (available in all projects)

# Clone
git clone https://github.com/222dotcrypto/claude-delegate.git /tmp/claude-delegate

# Copy script
cp /tmp/claude-delegate/scripts/spawn-delegate.sh ~/.claude/scripts/

# Copy commands
cp /tmp/claude-delegate/commands/*.md ~/.claude/commands/

# Make script executable
chmod +x ~/.claude/scripts/spawn-delegate.sh

Option 2: Per-project

# From your project root
git clone https://github.com/222dotcrypto/claude-delegate.git /tmp/claude-delegate

# Copy into project
mkdir -p .claude/scripts .claude/commands
cp /tmp/claude-delegate/scripts/spawn-delegate.sh .claude/scripts/
cp /tmp/claude-delegate/commands/*.md .claude/commands/
chmod +x .claude/scripts/spawn-delegate.sh

Commands

Command	Description
/delegate <task>	Create task file and spawn a new Claude Code agent
/delegate-check	Check status of all delegated tasks
/delegate-wait [task-id]	Wait for a specific task (or the latest one)
/delegate-clean	Archive completed tasks, clean up signals

Usage

Start Claude Code in your project and delegate:

> /delegate "Write unit tests for src/auth.py — cover login, logout, and token refresh"

Claude will:

1. Analyze relevant project files
2. Create a structured task file in .brain/delegates/
3. Spawn a new Claude Code instance in tmux
4. Continue your conversation (no waiting)

Check results later:

> /delegate-check

Or wait for completion:

> /delegate-wait

How delegates communicate

Everything is file-based:

• Tasks: .brain/delegates/task-{id}.md — structured task description with context
• Signals: .brain/delegates/signals/{id}.done / .failed — completion markers
• Results: .brain/delegates/results/{id}-result.md — delegate output
• Logs: .brain/logs/brain.log — spawn/completion events

Task file format

Each delegate gets a markdown file with frontmatter:

---
task: "Write auth tests"
status: pending
result_path: .brain/delegates/results/task-20260301-143022-result.md
signal_path: .brain/delegates/signals/task-20260301-143022.done
created: 2026-03-01T14:30:22Z
context_files:
  - src/auth.py
  - tests/conftest.py
---

## Task
Detailed description of what to do...

## Project Context
Stack, structure, constraints...

## Files to Study
- src/auth.py — main auth module
- tests/conftest.py — test fixtures

## Expected Result
- tests/test_auth.py with full coverage

## Acceptance Criteria
- [ ] All tests pass
- [ ] Coverage > 80%
- [ ] No TODO/FIXME stubs

Monitoring

Attach to the tmux session to watch delegates work:

tmux attach -t delegates
# Switch windows: Ctrl+B then window number
# List windows: Ctrl+B, W

Tips

• Delegates are fully autonomous — they can't ask you questions
• Write clear, specific task descriptions with acceptance criteria
• Include relevant context_files so the delegate knows what to read
• Use /delegate-check periodically or /delegate-wait to block until done
• Run multiple delegates in parallel for independent tasks

Project structure

claude-delegate/
├── scripts/
│   └── spawn-delegate.sh    # Launches Claude Code in tmux
├── commands/
│   ├── delegate.md           # /delegate — create and spawn
│   ├── delegate-check.md     # /delegate-check — status
│   ├── delegate-wait.md      # /delegate-wait — block until done
│   └── delegate-clean.md     # /delegate-clean — archive and cleanup
└── README.md

Runtime directories (created per-project):

.brain/delegates/
├── task-{id}.md              # Task files
├── .prompt-{id}.md           # System prompts (auto-generated)
├── results/
│   └── {id}-result.md        # Delegate output
├── signals/
│   ├── {id}.done             # Success marker
│   └── {id}.failed           # Failure marker
├── archive/                  # Cleaned up tasks
└── logs/
    └── brain.log             # Event log

License

MIT