Claude Code setup — parallel multi-agent starter kit

My Claude Code setup: an opinionated CLAUDE.md, plus
a working parallel multi-agent system — a skill that orchestrates fan-out work
and the role agents it spawns. Clone, run the installer, and you have a
plan → execute → review → merge pipeline that fans out across background
subagents (the default — in-process, isolated worktrees only where they write
in parallel, no extra setup).

The default path uses ordinary background subagents and (optionally) Workflows —
no experimental flags, no extra setup.

Fan-out uses significantly more tokens than a single session — use it for
parallel research, review, and feature work, not routine tasks.

What's inside

How it works

Only the lead (your main session) spawns. Every step delegates to a subagent
except the lead's own plan-mode authoring and gates; the parallel execution
step fans out into one background subagent per independent unit, each in its own
worktree (because they write concurrently and merge later):

PLAN (lead in plan mode: lead authors → plan-reviewer validates → ExitPlanMode) → you approve ─┐   ← the only approval gate
EXECUTE (N executor subagents, parallel, in worktrees)  ← contracts baked into each spawn prompt; no cross-talk
REVIEW (reviewer, read-only — no worktree)                 │
MERGE (merger) → removes each worktree+branch, reports completion
CODEX (lead) → one codex-challenge.sh <feature-base>..HEAD ─┘   ← triaged verdict, P0/P1 fixed

Pick the fan-out mechanism by need: background subagents by default;
Workflows for large/deterministic/resumable fan-outs. Worktree isolation
is added only where agents write in parallel and merge — read-only
fan-out (review, research) skips it.

Recommended models

Opus plans and writes code, and Sonnet handles lookups and mechanical work. The
planner runs deeper than the executors: same model, higher effort.

"Opus 5.5" is what the unpinned opus alias resolves to today — see Model
pinning. Executor spawns are sized to one concern each
(roughly ≤100 tool calls; the plan splits anything bigger).

Install

Recommended — let Claude Code install it (interactive wizard)

Open Claude Code and paste this:

Set up the Claude Code parallel-multi-agent kit from https://github.com/TurboKach/claude-code-setup — clone it to a temp directory, read INSTALL.md, and run it as an interactive install wizard. Detect what I already have and only install what's missing.

Claude checks your machine and walks you through it step by step: it offers to
install what you're missing (gstack), asks how to handle an existing
CLAUDE.md, which Opus version to pin, and which codex model the cross-review
gate should use — then enables the required settings and copies the skill +
agents with backups. Exactly what it does: INSTALL.md.

Alternative — non-interactive script

git clone https://github.com/TurboKach/claude-code-setup.git
cd claude-code-setup
./install.sh    # copies skill+agents+CLAUDE.md and merges settings; installs nothing else

The default path (background subagents + Workflows) needs no manual steps —
once the files are copied, ask for parallel work and it fans out.

Staying up to date

A SessionStart hook checks once a day whether this repo's master differs from the
SHA you installed — one cached curl to the GitHub API, silent unless there's news:

claude-code-setup: update available (installed abc1234 → remote def5678) — run /stack-update

If you edit the kit itself: commit first, then ./install.sh — the stamp is the checkout's HEAD at install time, so installing before the commit leaves it one behind and the hook reports your own push as an update. /stack-update applies it: clones the repo, summarizes what changed, and asks for your
approval before writing anything. Two state stamps track the update, not one — installed
(the SHA skills/agents/settings are at) and claude-md-installed (the SHA whose CLAUDE.md
you actually accepted). They diverge because install.sh never overwrites an existing
~/.claude/CLAUDE.md, and /stack-update lets you decline that merge — so a single stamp
would call the kit up to date while your CLAUDE.md sat stale and the change went missing.

Opt out with touch ~/.claude/.claude-code-setup/disabled.

Model pinning

The agent files pin models by alias (model: opus / model: sonnet; the
plan reviewer uses model: inherit), so they keep their semantic tiers — "heavy role" vs "cheap
role" — while one env var decides which concrete version each alias means.
Claude Code resolves the aliases through ANTHROPIC_DEFAULT_OPUS_MODEL /
ANTHROPIC_DEFAULT_SONNET_MODEL / ANTHROPIC_DEFAULT_HAIKU_MODEL /
ANTHROPIC_DEFAULT_FABLE_MODEL everywhere: the main session, agent
frontmatter, and per-spawn model choices. The fable alias is deliberately
left unpinned.

The kit leaves opus unpinned, so it follows the latest Opus. To hold a
version (a new Opus release then won't change or re-price your agents), install
with --opus-pin=<model id> or set it yourself:

"env": { "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5" }

install.sh removes the kit's earlier claude-opus-5 pin and leaves any other
value alone. The _SONNET_/_HAIKU_ variants pin those tiers the same way.

It also sets CLAUDE_CODE_SUBAGENT_MODEL to sonnet as a floor, not an
override: an agent definition's model: and an explicit per-spawn model both
take precedence over it. The pinned roles keep their frontmatter
pins (team-reviewer, the executors and fixer on opus; team-plan-reviewer's inherit also
outranks the floor and follows the session's model), and a per-spawn model: "opus" still wins — the floor only catches
a spawn with no pin anywhere (general-purpose, a bare Agent call — built-in
Explore is the exception, always capped at Opus regardless of this floor),
which would otherwise inherit whatever tier the master is running. Settings
env changes are read at session start — restart Claude Code after editing.

Requirements

Default path (background subagents + Workflows):

• Claude Code, current version — it auto-updates; claude --version if in doubt.
• That's it for the pipeline itself — no flags, no extra tools. The
  always-on codex gate (hard gate in global CLAUDE.md) is separate: it needs
  codex (codex-cli with --ephemeral support), gtimeout
  (brew install coreutils), and pgrep installed before your first push —
  the non-interactive installer installs none of them.

Recommended for the full workflow:

• gstack (optional) — the workflow's browser verification uses its
  /browse. Install:

  git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack \
    && cd ~/.claude/skills/gstack && ./setup
  

  Without gstack the team still works — verify web flows with another browser
  tool. The codex gate needs codex (codex-cli) and gtimeout
  (brew install coreutils), not gstack.

Notes

• The installer's default (--claude-md unset, i.e. "auto") mode never
  overwrites an existing ~/.claude/CLAUDE.md — a --claude-md=replace run
  backs it up and overwrites it. It backs up any skill/agent files it
  replaces (under ~/.claude/.backup-<timestamp>). It merges only the
  settings.example.json keys, with a settings.json.bak safety copy — and
  never overwrites a model pin you already set.
• settings.example.json is intentionally minimal — your real settings.json
  is personal; never commit it (it tends to hold emails, tokens, and private
  paths).

Credits

Workflow and parallel multi-agent system by @TurboKach.
gstack by Garry Tan. Built for
Claude Code. MIT licensed.