Thunk
WARNING: This Python implementation is deprecated. The active Bun + TypeScript rewrite lives at ../thunk-ts. New development should happen there.
Multi-agent ensemble planning CLI. Orchestrates multiple AI agents (Claude Code, OpenAI Codex) to collaboratively create implementation plans with human-in-the-loop review.
Why Thunk?
"A droid is only as good as its plan." Planning with multiple models produces more robust plans through:
- Diversity: Different models notice different things when exploring codebases
- Peer review: Agents critique each other's drafts before synthesis
- Iteration: Human feedback refines plans across multiple turns
Install
uv tool install git+https://github.com/gbasin/thunk
To update:
uv tool upgrade thunk
Quick Start
# Start a planning session
thunk init "Add user authentication"
# Wait for agents to complete first turn
thunk wait --session <session_id>
# Review and edit the plan
# Edit .thunk/sessions/<id>/turns/001.md
# Continue to next turn (incorporates your edits)
thunk continue --session <session_id>
# Approve when satisfied
thunk approve --session <session_id>
How It Works
Turn-Based Planning
Each turn follows this flow:
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ DRAFT │ -> │ PEER REVIEW │ -> │ SYNTHESIS │ -> │ USER REVIEW │
│ │ │ │ │ │ │ │
│ Each agent │ │ Agents │ │ Merge into │ │ Human edits │
│ writes plan │ │ review peer │ │ unified │ │ turns/001.md│
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
- Draft: Each agent explores the codebase and writes an independent plan
- Peer Review: Agents review each other's drafts and refine their own
- Synthesis: Plans are merged into a unified proposal
- User Review: Human edits
turns/NNN.md, then calls continue or approve
Session Continuation
Agents maintain context across turns via CLI session continuation:
- Claude Code:
--resume <session_id>
- Codex:
resume <thread_id>
This means agents accumulate codebase knowledge rather than starting fresh each turn.
User Feedback as Diff
When you edit turns/001.md and call continue, agents receive your changes as a diff. They interpret your edits naturally:
- Deletions = remove this
- Additions = add this requirement
- Comments = feedback to address
Commands
| Command | Description |
|---|
thunk init "task" | Start new planning session |
thunk wait --session <id> | Block until current turn completes |
thunk status --session <id> | Check progress without blocking |
thunk continue --session <id> | Start next turn after your edits |
thunk approve --session <id> | Lock plan as final |
thunk list | List all sessions |
thunk clean --session <id> | Remove session data |
thunk diff --session <id> | Show changes between turns |
File Structure
.thunk/sessions/swift-river/ # Human-friendly session ID
├── meta.yaml # Task description, timestamp
├── state.yaml # Turn, phase, agent_plan_ids mapping
│
├── sunny-glade.md # Agent's persistent plan (plan_id)
├── amber-marsh.md # Another agent's plan
│
├── turns/
│ ├── 001.md # Turn 1 synthesis (USER EDITS THIS)
│ ├── 001.snapshot.md # Pre-edit snapshot (for diffing)
│ ├── 001/ # Debug snapshots
│ │ ├── sunny-glade-draft.md
│ │ └── sunny-glade-reviewed.md
│ ├── 002.md
│ └── ...
│
├── agents/
│ ├── sunny-glade.log # Session-wide debug log (appended)
│ ├── sunny-glade/
│ │ └── cli_session_id.txt # For --resume
│ ├── amber-marsh.log
│ └── synthesizer.log
│
└── PLAN.md # Symlink to approved turn
Key points:
- Plan IDs (
sunny-glade, amber-marsh) are opaque names mapped to agents in state.yaml
- Agents read/write their persistent plan file (e.g.,
sunny-glade.md)
- After synthesis, all agent plan files are synced to the canonical state
- Debug logs span the entire session (appended each turn)
Configuration
Default agents (in code):
- opus: Claude Code with Opus 4.5
- codex: OpenAI Codex CLI
Both run from the project root with full read access and limited tool permissions for safe exploration.
Architecture
gbasin
gbasin
