Coordinate multiple Claude Code terminals on the same project without collisions. Use when the user wants to run 2+ Claude sessions in parallel on one repo, asks about multi-agent workflows, parallel Claude, terminal coordination, file locks, shared kanban boards, planner/architect roles, or how to avoid two AI sessions editing the same file. Provides interactive setup wizard, file-level lock protocol, shared task board, planner approval gate, configurable git workflow (single-branch or feature-branch), stale-lock detection with TTL, role-tailored terminal intros, and slash commands (/multi-agent-init, /agents-status, /agent-intro, /release-locks).
How this skill is triggered — by the user, by Claude, or both
Slash command
/multi-agent-coordination:multi-agent-coordinationThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
A reusable system for running multiple Claude Code terminals on the same project safely. Extracted from production use (Etihad CRM), generalized for any stack.
references/approval-gate.mdreferences/git-workflow-variants.mdreferences/lock-protocol.mdreferences/terminal-roles.mdreferences/troubleshooting.mdtemplates/CLAUDE-section.mdtemplates/active_files.mdtemplates/active_tasks.mdtemplates/intros/developer-intro.mdtemplates/intros/planner-intro.mdtemplates/intros/solo-intro.mdA reusable system for running multiple Claude Code terminals on the same project safely. Extracted from production use (Etihad CRM), generalized for any stack.
Activate this skill when the user:
P — reviews, never writes code) or Developer (labels T1, T2, T3, … — implements). See references/terminal-roles.md.active_files.md is a shared lock registry. Append a line before editing, remove after. Timestamped so stale locks expire. See references/lock-protocol.md.active_tasks.md has four sections (TODO / AWAITING REVIEW / BLOCKED / DONE). Single source of truth for what each terminal is doing. See references/lock-protocol.md (kanban section).references/approval-gate.md.references/git-workflow-variants.md.The system scales by terminal count — pick at setup time:
| Mode | Terminals | Composition |
|---|---|---|
| Solo | 1 | Just task tracking, no locks needed |
| Pair | 2 | 1 planner + 1 developer |
| Squad | 3–4 | 1 planner + 2–3 developers |
| Swarm | 5+ | 1 planner + N developers + extra rules |
/multi-agent-init) — interactive; asks the user every setting (mode, TTL, branch names, build/test commands, git variant) and writes a tailored config. Never assumes defaults silently./agent-intro) — when a fresh terminal starts, this command reads the saved config + asks which terminal number the session is, then prints a role-tailored intro that includes the lock protocol, kanban rules, commit rules, and any project-specific commands./agents-status) — shows the kanban + active locks + stale-lock warnings in one view./release-locks) — clean up locks held by the current terminal (use on session exit / crash recovery).When the user invokes /multi-agent-init, the wizard is built to feel fast. Most users finish in 3-5 prompts.
package.json / Cargo.toml / pyproject.toml / Makefile to propose build + test commands; runs git symbolic-ref to propose integration / production branches; uses the directory name for the project name. Presents them in one confirmation step: "Use these, customize commands, customize branches, or customize everything?"Presets cover ~95% of cases. Power users pick Custom for full control.
| Setting | Solo | Pair | Squad | Swarm |
|---|---|---|---|---|
| has_planner | false | true | true | true |
| lock_ttl_minutes | n/a | 15 | 15 | 15 |
| stale_lock_policy | n/a | auto-clear | warn | warn |
| git_variant | B | B | B | B |
| approval_gate_enabled | false | true | true | true |
| commit_format | conventional | conventional | conventional | conventional |
.multi-agent/config.json — all final settings (committed, not gitignored — team members get the same config on clone)active_tasks.md — empty kanban (from templates/active_tasks.md) — gitignoredactive_files.md — empty lock registry (from templates/active_files.md) — gitignored (skipped in Solo)CLAUDE.md — appended with the multi-agent section between BEGIN/END markers, interpolated with the user's answers.gitignore — patched to exclude only active_tasks.md and active_files.mdThen the wizard outputs N ready-to-paste intro blocks — one per terminal — tailored from templates/intros/. The user opens N terminals and pastes the matching intro into each.
Once /multi-agent-init finishes, the Planner terminal (the one that ran setup) outputs:
✅ Setup complete. Open N more Claude Code terminals in this project.
Then paste the following into each:
━━━ TERMINAL 1 (Developer A) ━━━
<contents of templates/intros/developer-intro.md, interpolated with config>
━━━ TERMINAL 2 (Developer B) ━━━
<same, with terminal number 2>
…
This way the user does not have to explain anything — every terminal gets onboarded automatically.
Before editing any file: read active_files.md. If the target path is listed by another terminal, wait 30s and recheck. If not listed, append - <path> → T<N> @ <ISO-timestamp> (developers — use P for the planner). Edit. Remove the line immediately when done. Locks older than the configured TTL are stale — any terminal may warn or auto-clear them per project policy. Full details and edge cases: references/lock-protocol.md.
Developers must not run git add / git commit / git push / gh pr create until the planner has reviewed the uncommitted diff and the user has relayed an explicit "approved" message. Developers signal readiness by moving the task to AWAITING REVIEW in active_tasks.md and saying so in chat. Planner verifies via git diff + typecheck + test + manual run, then approves or blocks. Exception: pure-docs / planning-file commits and explicit user-authorized hotfixes. Full flow: references/approval-gate.md.
Details, hotfix flows, and the rationale for Variant B: references/git-workflow-variants.md.
Stale locks after a crash, two terminals colliding on a task, planner unable to spawn sub-agents, conflicts during git pull --rebase, and what to do when CI goes red mid-coordination — all covered in references/troubleshooting.md.
| Path | Purpose |
|---|---|
references/terminal-roles.md | What each role does and what it MAY NOT do |
references/lock-protocol.md | Full lock + kanban protocol with edge cases |
references/approval-gate.md | Pre-commit review flow and exceptions |
references/git-workflow-variants.md | Variant A vs B, hotfix flow, release flow |
references/troubleshooting.md | Common breakage and recovery recipes |
templates/active_tasks.md | Empty kanban template |
templates/active_files.md | Empty lock-registry template |
templates/CLAUDE-section.md | Block to append to project CLAUDE.md |
templates/intros/planner-intro.md | Intro the planner terminal reads on session start |
templates/intros/developer-intro.md | Intro a developer terminal reads on session start |
templates/intros/solo-intro.md | Intro for the lite single-terminal mode |
~/.claude/plugins/multi-agent-coordination/. Available in every project automatically. Re-installing is only needed on new machines..multi-agent/config.json at the project root. Committed to git so collaborators cloning the repo get the same multi-agent settings without re-running the wizard.CLAUDE.md between BEGIN/END markers. Committed. Auto-loaded by every Claude Code session in that project, so terminals know the rules without explicit /agent-intro.active_tasks.md, active_files.md at the project root. Gitignored. These represent in-flight kanban + lock state, not durable config.This means: once a user installs the skill and runs /multi-agent-init in a project, that project is permanently configured. Every new terminal session loads CLAUDE.md + reads config.json automatically. No re-install per project.
active_files.md / active_tasks.md while another terminal holds a lock on them implicitly — these files are written by every terminal; treat appends as atomic single-line writes and re-read before every operation.Provides a checklist for code reviews covering functionality, security, performance, maintainability, tests, and quality. Use for pull requests, audits, team standards, and developer training.
npx claudepluginhub rahimjonovboburjon/multi-agent-coordination --plugin multi-agent-coordination