multi-agents-cli

A structured workflow tool that orchestrates multiple Claude Code agents working in parallel - each isolated in its own git worktree, owning a specific scope of the codebase.

Instead of one session carrying the entire build, each agent carries a narrower, domain-specific context. Shared state files carry progress between sessions and drive prerequisite-aware next-agent recommendations.

The result: each agent works on its own branch in its own worktree, and its git diff is checked against its permitted scope before it merges to main.

Install

npm install -g multi-agents-cli

Quickstart

multi-agents init my-project
cd my-project
npm run agent

multi-agents init will:

• Guide you through project name, stack, IDE, and build trajectory using arrow-key selection
• Generate BUILD_STATE.md, CONTRACTS.md, CLAUDE.md, CLOUD_STATE.md
• Generate shared/wiring.config.json with client/backend env var conventions
• Write .scaffold/.config.json, .scaffold/.tracking.json, .scaffold/scope-policy.json
• Copy agent instruction files and framework scaffold guides from the bundled core/
• Initialize git, install pre-commit hook, and create the initial commit

Commands

All commands self-relocate to the repo root via git rev-parse --git-common-dir. Run them from the worktree terminal, the repo root, or anywhere inside the git tree.

Workflow

1. Start a task

npm run agent

Select scope (client / backend / shared), then agent, then describe the task. The workspace opens in your IDE and Claude Code CLI launches automatically.

The agent reads TASK.md and executes autonomously.

2. Complete a task

npm run complete

Validates scope boundaries via git diff, merges the branch into main, updates BUILD_STATE.md and TASKS_HISTORY.md, and clears the tracking slot.

3. Repeat

Pick the next agent and continue building.

Build Trajectories

Choose during multi-agents init:

Multi-Agent Driven Orchestration (recommended) Every task starts with npm run agent. Each agent works in its own git worktree - an isolated branch and folder that merges back into main via npm run complete.

Shared Orchestration (experimental — not yet tested end-to-end) You and agents co-build - each owning a defined part of the codebase. Agent tasks run in git worktrees; your work happens directly in the project. Define boundaries before work begins.

Framework Guides

Client

Next.js - Angular - Vue/Nuxt - SvelteKit - Vite+React - Remix

Backend (separate)

Express - NestJS - Fastify - FastAPI - Django - Laravel - Rails

Each framework has a dedicated scaffold instruction file in .frameworks/client/ and .frameworks/backend/ - agents read these before scaffolding to ensure files land in the correct location.

Agent Roster

Client

Backend (separate only)

Shared

Start with UI (client) or INIT (backend). The launcher recommends the correct next agent dynamically based on what is already completed.

Scope Validation

The committed diff of every agent merge is validated before it touches main.

When a worktree is created, agent.js writes a scope.json file declaring the agent's identity and policy. When npm run complete runs, it:

1. Reads scope.json from the worktree
2. Loads .scaffold/scope-policy.json (written at init time)
3. Runs git diff --name-only main...HEAD to get every changed file
4. Blocks the merge if any file falls outside the allowed paths for that scope

Policy summary:

Scaffold-only overrides expire automatically after the first successful merge for that scope.

Wiring Config

shared/wiring.config.json is the client-backend interface contract for environment variables. It contains conventional variable names only - no values, no ports.

{
  "client": {
    "apiBaseUrlVar": "API_BASE_URL",
    "environments": {
      "development": {},
      "staging": {},
      "production": {}
    }
  },
  "backend": {
    "portVar": "PORT",
    "corsOriginVar": "CORS_ORIGIN",
    "environments": {
      "development": {},
      "staging": {},
      "production": {}
    }
  }
}

The UI agent populates the client section on first scaffold. The INIT agent populates the backend section. The CLOUD agent reads both sections to wire per-environment values correctly.

Remote Setup

multi-agents init does not configure a GitHub remote. The first agent session handles remote setup automatically:

1. Checks SSH, gh CLI, and HTTPS credentials in order
2. If a remote repo exists - evaluates its state (orphaned branches, completion status, age)
3. Auto-clears old sessions or surfaces a decision when unfinished work is detected
4. If no remote - opens your browser to github.com/new with the repo name pre-filled

Key Files

Never edit BUILD_STATE.md or TASKS_HISTORY.md directly. Workflow scripts own all updates.

Guard System

The launcher checks structural rules before any worktree is created:

• Skeleton guard - LOGIC/FORMS/ROUTING/TESTING require UI completed first (client), API requires INIT completed first (backend)
• Prerequisite check - surfaces unmet dependencies, lets you proceed or repick
• Active agent gate - if the same agent is already running, offers Resume / Restart / Cancel with cascade warnings
• MISSING gate - if a worktree was deleted without completing, mandatory Recover or Reset decision
• CLOUD gate - CLOUD agent is only selectable when client and/or backend prerequisites are met, shows readiness table

Architecture

my-project/
├── .agents/                        <- agent instruction files (bundled in core/)
│   ├── client/                     <- UI.md, LOGIC.md, FORMS.md, ROUTING.md, TESTING.md, ACCESSIBILITY.md
│   ├── backend/                    <- INIT.md, API.md, DB.md, AUTH.md, LOGIC.md, EVENTS.md, JOBS.md, TESTING.md
│   └── shared/                     <- CLOUD.md, SECURITY.md, CLOUD_TEARDOWN.md
├── .frameworks/                    <- framework scaffold instructions (bundled in core/)
│   ├── client/                     <- nextjs.md, angular.md, vite-react.md, nuxt.md, sveltekit.md, remix.md
│   └── backend/                    <- express.md, nestjs.md, fastify.md, fastapi.md, django.md
├── .workflow/                      <- workflow scripts (agent.js, complete.js, guards.js, reset.js, restart.js)
├── .scaffold/                      <- runtime state (.config.json, .tracking.json, scope-policy.json, .initialized)
├── client/                         <- built by client agents
├── backend/                        <- built by backend agents (if separate)
├── shared/
│   └── wiring.config.json          <- client-backend env var conventions
├── worktrees/                      <- local only, gitignored
├── CLAUDE.md
├── BUILD_STATE.md
├── CONTRACTS.md
├── TASKS_HISTORY.md
└── CLOUD_STATE.md

Each agent works in its own worktrees/ folder on a dedicated branch. On completion, scope is validated and work merges into main. The intended end state is a complete, runnable application on main.

Tracking

.scaffold/.tracking.json is the runtime state ledger:

{
  "client": {
    "UI": {
      "branch": "agent/client/ui/1780403456467",
      "status": "ACTIVE",
      "launchedAt": "2026-06-04T10:21:00Z",
      "missingCount": 0,
      "worktreePath": "/path/to/worktrees/..."
    }
  }
}

Status values: null (never launched) - ACTIVE (running) - COMPLETED (merged into main) - MISSING (worktree deleted without completing)

Managed entirely by agent.js and complete.js. Never edit manually.

Limitations

multi-agents-cli is a workflow layer around Claude Code, not a sandbox. Known limits as of v1.2.9:

• Completion-time check. Scope is validated once, at npm run complete, against the committed diff (git diff --name-only main...HEAD). It does not stop an agent from writing outside its scope while it works.
• Staged files are not re-validated. Files staged by the auto-commit at completion are not re-checked against the blocked list. This only matters where allowed and blocked patterns overlap in the shipped policy.
• No concurrent-write protection. Tracking and state files are written with plain fs.writeFileSync and no locking. Two commands running at the same moment can overwrite each other, and the last write wins.
• Shared Orchestration is untested. This trajectory has not been tested end-to-end. Treat it as experimental.
• No update path for scaffolded projects. sync can detect a stale .workflow/ directory but does not update it. Fixes to workflow scripts do not reach projects that were already scaffolded.

What's new in v1.2.9

Scope validation fix

• Fixed a path boundary bug in directory patterns. From v1.0.54 through v1.2.8, client/** also matched sibling paths that share the prefix (for example clientele/secret.ts or clientCONTRACTS.md), and backend/** matched backend-old/x.ts, so those files could pass scope validation and merge. Directory patterns now require the path separator.
• The same fix applies to preflight in-scope file detection, which uses the same matcher

Tests and release gate

• Added a test suite (npm test, built-in node:test, no new dependencies) covering glob matching, violation detection, scope resolution, and preflight decision paths
• npm publish now runs the tests first and aborts on failure (prepublishOnly)
• GitHub Actions runs the suite on Node 18 and 20 for pushes to main and pull requests

Internal

• preflight assess() accepts optional git and filesystem functions for testing; defaults are unchanged