Crews

A lightweight multi-agent CLI powered by Claude Code. Define a team of specialized AI agents, point them at a task, and let them implement, test, review — and loop until the code is ready.

Works with any codebase, any language. Zero npm runtime dependencies.

What makes Crews different

Most multi-agent tools are fan-out only — all agents run in parallel and you get N independent outputs. Crews adds two more patterns:

• Sequential pipelines — agents hand off to each other. Backend dev implements, QA writes tests using that output, architect reviews both.
• Retry loops with verdict extraction — a reviewer agent emits a Verdict: line. If it says "Needs fixes", the whole pipeline re-runs with targeted fix instructions prepended. Loops until "Ready to merge" or maxRounds is reached.

And because agents run as claude --print subprocesses, action agents can actually read and write files — they're not just producing text.

→ Architecture & design flow — how message composition, execution modes, and the retry loop work under the hood. → Writing agents — how to write role.md, prompt.md, and config.json for a new agent, with a worked example.

Prerequisites

• Node.js 18+
• Claude Code CLI installed and authenticated (claude --version should work)

Installation

# Option A — global install from npm
npm install -g crews-cli

# Option B — clone and link locally
git clone https://github.com/reutisr/crews
cd crews && npm link

Quick start

# 1. Set up .crews/ in your project
cd your-project
crews init

# 2. Edit .crews/directives.md with your project's rules
# (code style, security policies, testing conventions)

# 3. Scaffold some agents
crews create-agent backend-dev
crews create-agent code-reviewer
crews create-agent qa

# 4. Fill in each agent's role, prompt, and config
# .crews/agents/backend-dev/role.md      — role definition
# .crews/agents/backend-dev/prompt.md    — system prompt
# .crews/agents/backend-dev/config.json  — model, type, optional timeout

# 5. Create a task file (copy from examples/)
cp node_modules/crews-cli/examples/retry-loop.json my-task.json
# Edit description and context paths

# 6. Run it
crews run my-task.json

Concepts

Agents

An agent is a directory in .crews/agents/<name>/ with three files:

File	Purpose
role.md	Defines the agent's role, expertise, and boundaries. Injected into every message.
prompt.md	The system prompt passed to Claude.
config.json	Model, type (analysis or action), and optional timeoutMs.

Agent types:

• analysis — read-only. Gets Read, Grep, Glob tools only. Content of context files is embedded directly in the message.
• action — can read and write files, run commands. Gets bypassPermissions mode. Context files are passed as paths (agents read fresh disk state each round).

Tasks

A task is a JSON file you create per feature or workflow:

{
  "description": "Implement input validation for the /users endpoint",
  "agents": ["backend-dev", "qa", "code-reviewer"],
  "mode": "sequential",
  "context": ["src/routes/users.js", "test/routes/users.test.js"],
  "retry": {
    "maxRounds": 3,
    "reviewerAgent": "code-reviewer"
  },
  "finalAgents": ["git-push"],
  "aggregator": true
}

Field	Required	Description
description	Yes	What needs to be done. Be specific.
agents	Yes	Agent names in order (for sequential).
mode	Yes	"parallel" or "sequential"
context	No	File paths to inject as context.
retry	No	{ maxRounds: 1–10, reviewerAgent: "name" } — enables retry loop. Sequential only.
finalAgents	No	Agents to run once after the main loop (e.g. git-push). Skipped if max rounds are exhausted with a failing verdict.
aggregator	No	true to synthesize all outputs into aggregated.md.
skills	No	Skill names from .claude/skills/<name>/SKILL.md to inject.
claude_md	No	Paths to context files (like AGENTS.md) to inject into action agents.

Modes

Parallel — all agents run concurrently with the same input. Good for independent reviews.

task → [agent-1]  →  output-1
     → [agent-2]  →  output-2   →  aggregated.md (optional)
     → [agent-3]  →  output-3

Sequential — agents run in order, each receiving the previous agent's output.

task → [backend-dev] → output-1 → [qa] → output-2 → [architect] → output-3

Retry loop (sequential with maxRounds > 1) — loops until the reviewer says "Ready to merge":

Round 1: backend-dev → qa → architect → code-reviewer → "Needs fixes"
Round 2: backend-dev (with fix instructions) → qa → architect → code-reviewer → "Ready to merge"
         ↓
         finalAgents: git-push  ← only runs if verdict passed

The reviewer agent must emit a line starting with Verdict: — e.g. Verdict: Ready to merge or Verdict: Needs fixes. Multiple agents can emit verdicts; all must agree before the loop exits.

Directives

.crews/directives.md — permanent project rules injected into every agent on every run. Use it for:

• Security policies
• Code style rules
• Testing conventions
• What agents must never do

Decisions

.crews/decisions.md — accumulated architectural decisions. When the architect agent emits a ## New Decisions section in its output, Crews auto-appends it here. This builds up institutional memory across runs without manual upkeep.

Output

All outputs go to .crews/output/<task-name>/:

• Single-round: backend-dev.md, qa.md, architect.md, aggregated.md
• Multi-round: round-1/, round-2/, ..., git-push.md

Add .crews/output/ to .gitignore.

Project structure

your-project/
├── .crews/
│   ├── agents/
│   │   ├── backend-dev/
│   │   │   ├── role.md
│   │   │   ├── prompt.md
│   │   │   └── config.json
│   │   └── code-reviewer/
│   │       ├── role.md
│   │       ├── prompt.md
│   │       └── config.json
│   ├── directives.md     ← project rules for every agent
│   ├── decisions.md      ← auto-accumulated architectural decisions
│   └── output/           ← gitignored task outputs
└── tasks/
    ├── add-validation.json
    └── refactor-auth.json

Example agents to build

All 10 agents below are bundled into crews init — they're scaffolded automatically when you initialize a project. Customize any of them in .crews/agents/<name>/ for your stack.

Agent	Type	Role
backend-dev	action	Implements features, fixes bugs
frontend-dev	action	Implements UI features, components, and styling
qa	action	Writes and runs tests
test-runner	action	Runs the test suite and reports results — used in retry loops
git-push	action	Commits, pushes, opens PR — used as finalAgent
code-reviewer	analysis	Gates the retry loop — emits Verdict: line
architect	analysis	Reviews design decisions, appends to decisions.md
researcher	analysis	Pre-implementation codebase research
product-manager	analysis	Reviews against product requirements — emits Verdict: line
dr-compliance	analysis	Checks implementation against a spec/design doc — emits Verdict: line
task-verifier	action	Marks completed subtasks in a task list — emits Verdict: line

Dry-run mode

Set CREWS_MOCK=true to run a task without calling Claude. Each agent returns a mock output instantly — useful for testing your task JSON and agent configuration before spending real tokens.

CREWS_MOCK=true crews run my-task.json

You'll see the full summary table with timings and output paths, but no Claude calls are made and no files are modified.

Environment variables

Variable	Description
CREWS_MOCK=true	Dry-run mode — agents return mock output without calling Claude

Running tests

npm test

License

MIT