Mr. Burns

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:

./burns.sh

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

Loading

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>

Documentation

• Overview
• Glossary
• Architecture
• Configuration Guide
• Reference

References

• Gastown
• Cursor: Scaling Long-Running Autonomous Coding
• Claude Code Documentation