Mr. Burns is a small autonomous coding swarm for long-running engineering work. It now uses a fable-style role map:
| Role | Responsibility | Default runtime |
|---|---|---|
| Mr. Burns | Strategic oversight and go/no-go decisions | Claude Code |
| Smithers | Planning and task decomposition | Claude Opus via Claude Code |
| Homers | Parallel task execution | Codex with GPT-5.5 |
The orchestrator keeps each agent focused: Mr. Burns coordinates, Smithers plans, and Homers execute one task at a time. State lives on disk so every fresh agent session can recover context from files instead of memory.
Quick Start
Copy the example project file and edit it for your target repository:
cp state/project.example.json state/project.json
Set workingDirectory to the repo that should be modified, then run:
The default runtime is fable, which maps roles to their configured profiles. You can still force a single runtime for all roles:
./burns.sh --tool claude ./burns.sh --tool codex ./burns.sh --tool amp
Useful options:
./burns.sh --workers 8 ./burns.sh --exec-interval 5 ./burns.sh --max-cycles 200 ./burns.sh --project state/project.json
Runtime Configuration
Mr. Burns follows the same configuration shape as Gastown's role-to-agent settings: define named agents, then assign them through role_agents.
{
"agents": {
"claude-code": {
"command": "claude",
"args": ["--print", "--dangerously-skip-permissions"],
"prompt_mode": "stdin"
},
"claude-opus": {
"command": "claude",
"args": ["--print", "--model", "opus", "--dangerously-skip-permissions"],
"prompt_mode": "stdin"
},
"codex-gpt-5.5": {
"command": "codex",
"args": [
"exec",
"--model",
"gpt-5.5",
"--sandbox",
"danger-full-access",
"--ask-for-approval",
"never",
"--skip-git-repo-check",
"-"
],
"prompt_mode": "stdin"
}
},
"role_agents": {
"mr_burns": "claude-code",
"smithers": "claude-opus",
"homer": "codex-gpt-5.5"
}
}Built-in profiles are available for claude-code, claude-opus, codex, codex-gpt-5.5, and amp. Project files may use either snake_case (role_agents, prompt_mode) or camelCase (roleAgents, promptMode).
Architecture
graph TB
Project["Project config"]
Burns["Mr. Burns<br/>executive"]
Smithers["Smithers<br/>planner"]
Tasks["state/tasks<br/>task queue"]
Homer1["Homer 1<br/>Codex GPT-5.5"]
Homer2["Homer 2<br/>Codex GPT-5.5"]
HomerN["Homer N<br/>Codex GPT-5.5"]
Project --> Burns
Burns --> Smithers
Smithers --> Tasks
Tasks --> Homer1
Tasks --> Homer2
Tasks --> HomerN
Homer1 --> Tasks
Homer2 --> Tasks
HomerN --> Tasks
Tasks are claimed with atomic file moves. If two Homers try to claim the same pending task, one wins and the other moves on.
Repository Layout
mrburns/
├── burns.sh # Main shell orchestrator
├── docs/ # Concept, architecture, and usage docs
│ ├── overview.md
│ ├── glossary.md
│ ├── reference.md
│ ├── concepts/
│ ├── design/
│ ├── examples/
│ └── guides/
├── prompts/
│ ├── executive.md # Mr. Burns instructions
│ ├── planner.md # Smithers instructions
│ └── worker.md # Homer instructions
├── lib/
│ ├── task.sh # Task queue operations
│ ├── agent.sh # Agent registry and heartbeat helpers
│ └── git.sh # Git branch helpers
├── state/
│ └── project.example.json # Tracked example config
└── flowchart/ # Interactive visualization
Live runtime files such as state/project.json, state/tasks/, state/agents/, and state/logs/ are local working state and are ignored by git.
Signals
Agents communicate completion back to the orchestrator with stable XML-like signals:
<burns>CONTINUE</burns>
<burns>COMPLETE</burns>
<burns>STUCK</burns>
<burns>SPAWN_PLANNER:area</burns>
<burns>PLANNING_DONE</burns>
<burns>TASK_COMPLETE:TASK-001</burns>
<burns>TASK_FAILED:TASK-001:reason</burns>