multi-agents-cli weekly downloads statistics

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 and stays token-efficient. Shared state files carry progress between sessions and drive prerequisite-aware next-agent recommendations.

The result: faster builds, lower token spend, and a clean git history - without sacrificing reliability or context.

---

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

Command	Purpose
npm run agent	Start a new task with an agent
npm run complete	Merge agent work into main and update project state
npm run restart	Wipe and relaunch a specific agent
npm run reset	Nuclear wipe - removes all worktrees and resets project state
npm run init	Re-run initialization (locked after first run)

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. Faster builds and lower token spend than a single long session.

Shared Orchestration (experimental — less battle-tested than the multi-agent-driven path) 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.

---

Supported Frameworks

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

Agent	Default task	Requires
UI	Scaffolds full project structure + client wiring config	-
LOGIC	State management, API integration, hooks	UI done
FORMS	Form components, validation, submission	UI done
ROUTING	Page routing, navigation, URL structure	UI done
TESTING	Unit and integration tests	UI done
ACCESSIBILITY	a11y compliance, keyboard navigation	UI done

Backend (separate only)

Agent	Default task	Requires
INIT	Scaffolds backend structure, wiring config, CONTRACTS.md	-
API	REST/GraphQL endpoint implementation	INIT done
LOGIC	Business logic, services, data processing	API done
AUTH	Authentication, authorization, sessions	API done
DB	Database schemas, migrations, queries	INIT done
EVENTS	Event queues, pub/sub, webhooks	API done
JOBS	Background jobs, scheduled tasks	API done
TESTING	API and integration tests	API done

Shared

Agent	Default task	Requires
CLOUD	Deployment config, CI/CD, environment wiring	Client + backend done
SECURITY	Shared auth utilities, encryption, validation	-

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

---

Scope Validation

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:

Scope	Allowed	Blocked
client	client/**	backend/**, shared/**, CONTRACTS.md
client/UI (scaffold only)	client/**, shared/wiring.config.json	backend/**, CONTRACTS.md
backend	backend/**	client/**, shared/**, CONTRACTS.md
backend/INIT (scaffold only)	backend/**, shared/wiring.config.json, CONTRACTS.md	client/**
shared/CLOUD	deployment files only	client/**, backend/**, CONTRACTS.md

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

---

Wiring Config…