claudespace

A small software team of Claude Code agents, in one command.

Why

One AI session doing everything drifts. It redesigns while it builds, then reviews its own work and passes it.

claudespace splits the job the way a real team does. Each role is its own Claude Code session with one job, and none can see the others' conversation. The builder can't quietly change the plan. The reviewer can't grade its own homework. You describe what you want once, and the work moves itself from role to role.

How it works

you → chief → researcher → planner → principal → implementer → reviewer → PASS → you
                                                      ↑            │
                                                      └─ changes ──┘

| Role | Its job | |---|---| | chief | Reads your request and sends it to the right place. Start here. | | researcher | Finds out how things work today. | | analyst | Digs into anything murky, or something that already went wrong once. | | planner | Decides what to build. | | principal | Decides how to build it. | | implementer | Writes the code and tests. | | reviewer | Checks it. Says PASS or sends it back. | | conductor | Takes a big goal, turns it into a list, and works through it. |

Small fixes skip straight to the implementer. Real features go through the whole line. Only the implementer (and analyst, for tests and experiments) can change code; everyone else is read-only.

When does analyst step in?

Analyst is the most expensive role, so it only gets work that has already proven hard:

• Something that has been tried before and came back wrong.
• A problem that's murky or disputed, where nobody is sure what's actually true.
• A run the reviewer has rejected twice (on bug fixes, or where a design already existed).
• Any item stuck bouncing between roles without landing.

It never gets used just because chief isn't sure. A first-time bug with a clear repro goes straight to the implementer.

Install

Needs macOS (Apple Silicon) or Windows, and Claude Code installed and logged in.

npm i -g @ayorcodes/claudespace

Open a new terminal if claudespace isn't found.

Use it

cd ~/your-project
claudespace

Type what you want into chief, in plain words:

add rate limiting to the /api/upload endpoint

That's it. Panes open as work reaches them, and the reviewer reports back when it's done. Running claudespace again in the same folder reattaches.

For a bigger goal, say so. Chief hands it to conductor, which writes a backlog and pauses so you can edit it. Say go and it runs the list unattended.

Tips

• Always start in chief, even for tiny changes. Picking the right role is its job.
• For a big log or diff, save it to a file and paste the path, not the text.
• A permission prompt has to be answered in the pane that shows it.

Models and cost

Each role runs at a tier that decides which model it gets and how hard it thinks:

| Tier | Used by (default) | Claude model | |---|---|---| | max | analyst | Opus, high effort | | deep | conductor | Opus, medium effort | | standard | chief, planner, principal, implementer, reviewer | Sonnet, medium effort (reviewer: high) | | light | researcher | Sonnet, low effort |

claudespace --list-templates shows exactly what each role runs today.

Saver mode

claudespace --saver

With the defaults, every role always runs at its own tier. With --saver, each handoff can choose the model for the next step based on how hard that step is. An easy follow-up drops to a cheaper model, and a hard one moves up. Role panes also skip loading your MCP servers, because their tool lists add tokens to every turn. Analyst's tier is never lowered.

Setting your own models

To change one role's tier:

claudespace config set roles.reviewer deep

For finer control, edit ~/.config/claudespace/templates.toml. It's created on first run, and claudespace update leaves it alone.

# Give a role a different tier on every agent
[roles]
planner = "deep"

# Define your own tier for Claude and assign it to a role
[agents.claude.tiers]
heavy = "--model claude-opus-5-5 --effort high"

[agents.claude.roles]
reviewer = "heavy"

Or create a named template that pins exact commands, then run it with claudespace --template max:

[templates.max]
layout     = "default_main_left_grid_right"
entry_role = "chief"
roles      = ["chief", "conductor", "researcher", "analyst", "planner", "principal", "implementer", "reviewer"]

[templates.max.commands]
principal = "claude --model claude-opus-5-5 --effort high"

Every run also has a spending cap (default $20). When it's reached, the run pauses and asks you whether to raise the cap, deliver what's done, or cancel.

What it runs on

Agents

| Agent | Support | |---|---| | Claude Code | Full. Built and tested for it. | | Codex | Works, but experimental. Expect rough edges. | | Cursor Agent | Works, but experimental. Expect rough edges. |

Claude is the default. Pick another with claudespace --agent codex (or cursor).

Terminals

| Terminal | Platform | How to use it | |---|---|---| | cmux | macOS | Default. Installs itself on first run. | | Ghostty (via tmux) | macOS | claudespace --ghostty | | herdr | macOS | claudespace --herdr (opt-in) | | Hub (one terminal) | macOS | claudespace --hub. Chief runs in your terminal and the other roles run as Claude Code background sessions. Claude only. | | psmux | Windows | Default on Windows. Set up by the npm install. |

Linux isn't supported.

Handy commands

claudespace status     # what's working, what's stuck, what needs you
claudespace init       # teach it your project's test, lint and build commands
claudespace --hub      # everything in one terminal instead of split panes
claudespace --manual   # you press Enter on every handoff
claudespace close      # stop every role for this folder
claudespace doctor     # something broken? run this first
claudespace update     # update to the latest version

Uninstall

claudespace uninstall && npm rm -g @ayorcodes/claudespace

Run uninstall first. It removes the hook claudespace added to Claude Code.

More

Every flag, mode and setting: docs/reference.md.

License

Proprietary. See LICENSE.