Kitchen

Keep one AI focused on the big picture while a brigade of AI coding agents does the work.

Kitchen turns a Claude Code session into a hands-on engineering lead. That sous chef hires Claude, Codex, or Gemini cooks in tmux, gives them focused tickets, and receives their completed work automatically through Claude Code channels. You keep talking to one coherent orchestrator while the cooks spend their own context reading code, running tests, implementing changes, and reviewing one another.

It runs the stock agent CLIs you already use—authenticated through your existing subscriptions—not stripped-down API workers hidden behind a custom harness.

Why kitchen?

Benefit	Why it matters
A manager that stays sharp	The sous delegates source reads, greps, tests, and implementation instead of filling its own context with project detail. Its context stays available for coordination, tradeoffs, and long-running continuity.
Real agents, on your existing subscriptions	Cooks are ordinary Claude Code, Codex, and optionally Gemini/agy sessions. They keep their native tools, skills, plugins, MCP servers, and subscription auth; no separate model API integration or metered API-key billing is required. Provider usage limits still apply.
An opinionated workflow you can actually edit	sous-chef.md and the role prompts encode a complete operating method: delegate investigation, write verifiable tickets, review across backends, preserve decisions, and prove completion. They are plain Markdown—fork them, tune them, or replace the methodology.
Cross-model review by design	The supplied workflow pairs a Claude implementer with a Codex reviewer, or vice versa. An adversarial second model often catches assumptions the first model rationalized past. The convention lives in the prompt, so you remain in control.
Parallel work without a black box	Each cook is an isolated tmux window. Run independent workstreams concurrently, attach to watch them live, inspect a pane with kitchen peek, or take over the keyboard yourself.
Memory that survives the shift	Per-project mistakes.md and preferences.md files persist across kitchens, while per-kitchen notes support handoffs and task briefs. The team can carry forward lessons without keeping every old conversation alive.

Kitchen also integrates the superpowers skills workflow for brainstorming, specs, chunked implementation, review, and verification. For heavier use cases it can hand an independent workstream to another kitchen's sous with a ticket, or launch a clean-room Claude/Codex cook for a more reproducible evaluation—but the core stays deliberately small: tmux down, hooks and a Unix socket back up.

The mental model

                         your terminal
  you  <────────────>  sous chef (Claude Code)
                              │       ▲
                kitchen ticket│       │MCP channel notification
                              ▼       │
                    tmux session      │
                 ┌────────┼────────┐  │
                 │        │        │  │
              Claude    Codex   Gemini/agy
               cook      cook      cook
                 │        │        │
                 └────────┴────────┘
                      completion hooks
                              │
                    per-kitchen Unix socket

There are two intentionally simple directions:

• Sous → cook: kitchen ticket pastes a message into the cook's tmux composer and verifies that the TUI accepted it.
• Cook → sous: the agent CLI's completion hook sends the cook's full final response to a per-kitchen Unix socket. A tiny MCP channel server pushes it into the sous's live context—no polling and no pane scraping for results.

For the implementation details, diagrams, backend contracts, and the hook → socket → MCP flow, see How kitchen works.

A quick taste

Open a kitchen in a Git repository:

kitchen open

Claude starts as the sous chef in your terminal. Give it the outcome you want:

Build the import feature. Have one model implement it, another review it,
and run an end-to-end verification before you report back.

The sous can turn that into a flow like this:

kitchen hire eng --backend claude --role eng
kitchen hire reviewer --backend codex --role reviewer
kitchen ticket eng "Implement the agreed import feature and verify it end to end."

# eng's response arrives automatically in the sous's context
kitchen ticket reviewer "Review the import implementation. Do not edit; report findings."

You continue talking to the sous while both cook sessions remain visible in tmux. The supplied workflow reuses cooks when their context is valuable, routes findings back to the implementer, and requires evidence before declaring the work done.

Requirements

Required

• tmux — cooks run in tmux windows; this is the process and observation layer.
  • Verify: tmux -V
  • Install: brew install tmux on macOS, or use your Linux package manager.
• git — kitchen derives the project namespace from the repository and uses git worktrees for named kitchens.
  • Verify: git --version
• uv — installs the Python 3.12+ CLI and its dependencies.
  • Verify: uv --version
• Claude Code CLI 2.1.80 or newer — the sous uses Claude Code's development channels feature.
  • Verify: claude --version
• claude.ai web authentication — channels are available to claude.ai logins, not Console/API-key authentication.
  • Sign in: claude /login, then choose your claude.ai account.
• superpowers plugin — the supplied sous workflow invokes its brainstorming and development skills.
  • Install from Claude Code: /plugin install superpowers@claude-plugins-official (the superpowers-marketplace install also works)
• mcp Python SDK — installed automatically as a transitive dependency of this project; no separate install step is needed.

Optional backends and tools

• Codex CLI — required only for --backend codex cooks. Kitchen forces its completion notify command per cook launch, so ~/.codex/config.toml needs no kitchen entries.
• Antigravity CLI (agy) — required only for the opt-in --backend gemini cook. Kitchen does not use a gemini binary and kitchen setup does not install or check agy.
• jq — needed only by the packaged richer statusline example, not by the kitchen core.

Install

1. Install the system tools

On macOS:

brew install tmux git
curl -LsSf https://astral.sh/uv/install.sh | sh

On Linux, install tmux and git through your package manager, then install uv with the command above.

2. Install Claude Code and authenticate

Install Claude Code using its official instructions, then sign in with a claude.ai account:

claude /login

Kitchen's channel connection will not work with Console/API-key authentication.

3. Install superpowers

From inside Claude Code:

/plugin install superpowers@claude-plugins-official

4. Clone and install kitchen

git clone git@github.com:plonkus/kitchen.git
cd kitchen
uv tool install --editable .

The editable install makes changes to this checkout—including prompt customizations—available to the installed kitchen command immediately.

5. Run the setup diagnostic

kitchen setup

kitchen setup installs and verifies:

1. Claude Stop and UserPromptSubmit hooks: it appends a kitchen hook entry to ~/.claude/settings.json for each event that lacks one, after a settings.json.bak-kitchen-<time> backup, and leaves every other setting alone.
2. The mcp Python SDK.
3. The superpowers plugin.
4. Claude Code version 2.1.80 or newer.
5. That no legacy kitchen uses the reserved name projects.

The statusline check is advisory. Re-run the command until the blocking checks are green.

Quick start

Run kitchen from inside any git repository:

# Use the current checkout
kitchen open

# Or create a branch + sibling worktree for a named kitchen
kitchen open my-feature

The current process becomes the Claude sous chef. Talk to it normally—describe goals, constraints, and what evidence you expect. The sous knows the kitchen commands and manages cooks for you.

In another terminal, watch the brigade:

tmux -L ck-<project-slug>-<kitchen-name> attach

Each kitchen runs on its own tmux server (socket ck-<kitchen>), so the -L is required — a bare tmux attach -t ck-… will not find the session. No -t is needed: the server holds a single session, named kitchen, whose windows are kitchen:<cook>. kitchen open prints the exact command.

Kitchen namespaces sessions and state by project slug. For example, kitchen open my-feature in a repository named widget becomes kitchen widget-my-feature, while the git branch and worktree keep the name my-feature. A no-name kitchen open usually uses the repository name without doubling it.

Useful requests to give the sous

Hire a Claude engineer to investigate the flaky integration test.

Have a Codex reviewer inspect the engineer's commit for correctness and scope.

Split the migration into independent workstreams and run them in parallel.

Use a clean-room cook in /tmp/eval-checkout to evaluate this prompt.

Clock out the docs cook; keep the reviewer around for the next change.

CLI reference

The sous runs these commands under the hood. You can also use them directly from another terminal.

Command	What it does
kitchen open [name] [project]	Open a kitchen; an explicit name creates a worktree.
kitchen hire <cook> [options]	Spawn a cook and wait until its interactive prompt is ready.
kitchen roles	List the packaged cook roles.
kitchen ticket <cook> "message"	Deliver a verified message to a cook.
kitchen ticket sous --kitchen <kitchen> "message"	From a sous, deliver a ticket to another kitchen's sous over its channel socket; exits non-zero if that sous is not listening.
kitchen peek <cook> [--full]	Capture the cook's current pane or full scrollback.
kitchen brigade [kitchen]	Show live cook status and known context usage.
kitchen clock-out <cook>	Hard-kill a cook and remove its managed state.
kitchen sweep	Remove state files for cook windows that no longer exist.
kitchen close [kitchen]	Shut down the kitchen and remove managed per-kitchen state.
kitchen setup	Install hooks; check dependencies and environment readiness.

Hire options

# Packaged role; _default is used when --role is omitted
kitchen hire eng --backend claude --role eng

# Cross-model reviewer
kitchen hire reviewer --backend codex --role reviewer

# Unified effort scale: low, medium, high, max
kitchen hire investigator --effort max

# Claude model tier; the Claude CLI resolves the current model in that tier
kitchen hire architect --model opus

# Codex model; astra is passed to `codex -m` as gpt-6-astra (Codex cooks only)
kitchen hire reviewer --backend codex --model astra

# Near-fresh eval worker: no role, auto-memory, or superpowers startup injection
kitchen hire eval1 --clean-room --project /absolute/eval-directory

# Add a specific skill/plugin directory back to a clean-room Claude cook
kitchen hire eval2 --clean-room --with-skill /absolute/path/to/skill

Claude cooks receive role Markdown as an appended system prompt. Codex receives it as the first message after the TUI is ready, and Gemini/agy receives it as its initial turn. Clean-room mode supports Claude and Codex; --with-skill currently supports Claude only. Clean-room mode does not hide files such as CLAUDE.md or AGENTS.md from the cook's working directory, so use an empty directory or pinned checkout when that isolation matters.

Each Codex cook's thread is named [<kitchen>/<cook>] at hire and archived with codex archive on kitchen clock-out or kitchen close, so cooks stay out of the ChatGPT app's session list. Clean-room Codex cooks are skipped. If the ChatGPT app holds the thread, the archive fails with a one-line note and the clock-out continues.

How completion notifications work

Every launched agent gets AGENT_NAME, AGENT_KITCHEN, and STATUS_DIR. Global hooks are gated on those variables, so ordinary agent sessions outside a kitchen are untouched. Every launched agent also gets CLAUDE_CODE_DISABLE_AUTO_MEMORY=1, so durable notes go to the kitchen wiki rather than Claude Code's auto-memory.

When a cook completes a turn:

1. Claude's Stop hook, Codex's notify, or agy's stop hook invokes kitchen.
2. Kitchen stores the full final response and any available context information in the cook's status JSON.
3. The hook sends one JSON line to ~/.claude-kitchen/<kitchen>/kitchen.sock.
4. The per-kitchen MCP server emits a Claude channel notification.
5. The response appears automatically in the sous's context, and the sous decides whether to follow up, review, iterate, or report back.

The sous's own Stop hook does not notify its own socket, preventing an echo loop.

Where state lives

~/.claude-kitchen/
├── <kitchen>/
│   ├── kitchen.json          # source/worktree + sous resume session
│   ├── kitchen-mcp.json      # generated per-kitchen MCP config
│   ├── kitchen.sock          # live channel socket
│   ├── sous.pid              # duplicate-sous guard
│   ├── cooks/<name>.json     # backend, status, response, session, context
│   ├── codex-home/           # clean-room Codex homes, when used
│   ├── plow-chat/            # optional: plow-credentials (600), last_seen.json
│   └── notes/                # handoff, log, and long task briefs
└── projects/<slug>/wiki/
    ├── mistakes.md           # durable lessons
    └── preferences.md        # durable working preferences

kitchen close removes managed per-kitchen notes and cook state. The project wiki survives so later kitchens inherit the lessons and preferences.

Texting the sous (plow-chat)

A kitchen whose state dir holds plow-chat/plow-credentials also loads the plow-chat channel when kitchen open starts its sous. Texts to that Plow line arrive as <channel source="plow-chat" from="<name>" chat="<chat uid>">; photos and files sent with them are saved under plow-chat/files/ and their space-separated paths added as a file attribute. The sous answers with its reply tool, or sends up to four local files as one message with send_file. There is no allowlist: Plow delivers only chats the line's account owns, meaning the owner's 1:1 and any iMessage group the owner was in when its first text arrived. Every member of those chats speaks with head-chef authority. Anyone who has both numbers can start such a group, so the owner should treat every group with the line as trusted.

Setup, using latch and the kitchen name kitchen open prints (a kitchen boss opened in a widget repo is widget-boss):

latch login                       # text the printed code from your phone
latch agents lines                # pick a free line
mkdir -p -m 700 ~/.claude-kitchen/widget-boss/plow-chat
latch agents new --own --name widget-boss --line ln_... \
  --credential-file ~/.claude-kitchen/widget-boss/plow-chat/plow-credentials

Then restart the sous: /exit, then kitchen open --resume boss from the project root. Text the line to check it. A new group needs no setup: add the line's number to it.

Customize the workflow

The orchestration behavior is intentionally not hard-coded:

• src/claude_kitchen/sous-chef.md defines the manager's operating method: protect context, delegate investigation, use superpowers for spec work, review across models, preserve decisions, and require evidence.
• src/claude_kitchen/roles/ contains the cook contracts: eng, reviewer, qa, and _default.
• .kitchen/on-open.sh and .kitchen/on-close.sh in a project can run lifecycle automation for that repository.

With an editable install, reopen the kitchen or re-hire a cook after changing a prompt to pick up the new behavior. For long-lived customization, fork the repository and install your fork.

Troubleshooting

• server:kitchen · no MCP server configured at sous startup: this is a known harmless startup race; the server connects shortly afterward.
• Superpowers is missing: install it from Claude Code with /plugin install superpowers@claude-plugins-official (the superpowers-marketplace install also works).
• Channel authentication fails: run claude /login and select a claude.ai account. Console/API-key authentication does not expose channels.
• Claude Code is too old: upgrade to version 2.1.80 or newer.
• agy not on PATH: Gemini cooks require Antigravity CLI; Claude and Codex kitchens do not.
• Named kitchen refuses to open outside a git repository: a plain directory works for an unnamed kitchen open (a home kitchen), but kitchen open <name> makes a git worktree, so it needs a repository.
• Legacy kitchen named projects: that name is reserved for the persistent project wiki root; follow the rename instruction printed by setup.

Acknowledgements

Kitchen was inspired by two projects we admired and learned from. We re-implemented their ideas in our own Python—no code was copied.

• firstmate — we studied its tmux send/verify approach (verified-submit, prompt-suggestion/ghost-text suppression, busy-footer detection) and re-implemented those ideas ourselves.
• mypeople — general inspiration for orchestrating multiple Claude Code agents through a single channel server.