Aicrew

aicrew

[](LICENSE) [](package.json)

A TDD-first AI development pipeline for Claude Code, Cursor, Codex, Gemini CLI, and Antigravity.

One command set and one source of truth across every major AI coding tool — install once, drive your whole SDLC from a handful of commands.

---

Install (30 seconds)

npx aicrew status                # no install — shows what you'd get
npx aicrew install               # all platforms
npx aicrew install claude|cursor|codex|gemini   # one platform
npx aicrew doctor                # verify MCP server binaries are reachable

Requirements: Node 18+. No extra Python packages and no npm runtime dependencies.

> MCP server binaries (graph index, token optimizer) install separately — see MCP setup under Advanced below, or run npx aicrew install mcp.

---

Demo

Terminal walkthrough: status + doctor, slash-command help, phase-by-phase gates (TDD, security), and live aicrew benchmark output — not static cards.

---

The three commands you actually use

/dev — full pipeline

9-phase pipeline: intake → research → brainstorm → design → implement (TDD) → tests → security → audit → conclude. Every phase stops and waits for your go-ahead.

> Use when: a new feature, a refactor, or anything that needs a design spec or touches multiple systems.

/dev Add rate limiting to the auth API

Codex: aicrew-dev

/fix — fast bug fix

3 intake questions, then TDD straight to done. Skips brainstorm and design phases.

> Use when: you can describe what's broken and want it fixed.

/fix OAuth redirect returns 500 after login

Codex: aicrew-fix

/quick — scoped task, lowest tokens

Scout → Act. A cheap model (context-scout) runs graph-first discovery (graph query ~500 tok; Scout pass may also use targeted diff/tree reads) and emits a fixed SCOUT: schema (~1–2 K); the main model acts from that block only — no pipeline overhead.

> Use when: a rename, a tweak, or a small well-defined addition.

/quick Rename UserService to AccountService across the repo

Codex: aicrew-quick

| Situation | Use | |-----------|-----| | New feature, refactor, or anything needing a design spec | /dev | | Bug fix — you know what's broken | /fix | | Small scoped task — rename, tweak, quick addition | /quick |

How discovery works: A cheap discovery pass (Scout) maps the repo via graph + targeted reads and writes a ~1–2 K SCOUT: summary. The main model verifies paths and constraints, then implements from that summary—not full grep dumps. aicrew defines Scout vs Act roles; your tool (Cursor, Claude Code, Codex, etc.) picks the models. [Scout → Verify → Act](docs/pipeline-overview.md#scout--verify--act) and [model routing](docs/pipeline-overview.md#model-routing) in [pipeline-overview.md](docs/pipeline-overview.md).

Why aicrew (pipelines, benefits, token savings)

Pipeline depth (same token stack, different ceremony)

| Command | Phases | Use when | |---------|--------|----------| | /dev | 9 — intake → research → brainstorm → design → implement (TDD) → tests → security → audit → conclude | Feature, refactor, or anything needing a design spec | | /fix | 5 — intake → bug analysis → implement (TDD) → tests → security → conclude | Bug fix with mandatory TDD | | /quick | 2 — Scout → Act | Scoped task; graph-first without pipeline overhead |

Benefits

• TDD-first — strict RED → GREEN → REFACTOR in /dev and /fix; tests before or with implementation
• Phase gates — every phase stops for your explicit go-ahead; the agent never invents your response
• Security review — security-reviewer on changed files; security-guard.py blocks secrets on every write
• Scout → verify — cheap model maps the problem; capable model acts from a verified summary only

Token savings (illustrative figures — project-dependent)

• Graph query ~500 tok vs repo-wide grep ~80 K (documented ratio; [token-foundation.md](./skills/docs/token-foundation.md))
• Scout block ~1–2 K SCOUT: schema from context-scout vs reading raw grep/file dumps (often 10–80 K+ depending on repo; [speculative-context.md](./skills/docs/speculative-context.md))
• /handoff ~300 tok vs ~15 K chat replay (estimated)

All three commands share the same 11-capability token foundation — only pipeline depth differs.

• [Scout → Verify → Act](docs/pipeline-overview.md#scout--verify--act) — discovery flow and per-command Scout timing
• [Model routing](docs/pipeline-overview.md#model-routing) — Scout vs Act roles and cheap-model guidance

[Full pipeline reference →](docs/pipeline-overview.md)

---

Advanced

Full command list (daily + maintenance)

Beyond the three core commands, aicrew ships a small set of daily utilities and a few rarely-used maintenance commands.

Daily utilities

| Command | Codex skill | What it does | |---------|-------------|--------------| | /conclude | aicrew-conclude | End session — saves learnings, proposes commit message | | /session | aicrew-session | Name this task so state files don't collide | | /handoff | aicrew-handoff | Compact summary (~300 tokens) when switching tools | | /brainstorm | brainstorm | 3 design options with trade-offs before any code | | /lean | lean | Toggle verbosity — default terse; /lean on amplifies; /lean off (aka /normal) restores verbose |

Maintenance (rare)

| Command | Codex skill | What it does | |---------|-------------|--------------| | /update-skills | aicrew-update-skills | Refresh or generate project-specific skills | | /harness-audit | aicrew-harness-audit | Health-check your aicrew install | | /benchmark | aicrew-benchmark | Estimate tokens saved (writes .ai/reports/TOKEN_REPORT) |

Cross-tool handoff

Switching tools mid-task (Claude → Cursor)? Each switch costs ~300 tokens instead of ~15,000.

1. Name the session early: /session cursor my-feature → state file .ai/state/AI_STATE.cursor.my-feature.md
2. When ready to switch: /handoff
3. In the new tool: Continue from .ai/state/AI_STATE.cursor.my-feature.md

/normal is kept as an alias of /lean off. Setup actions (install, update, status, agent-kit, cursor-plugin) are CLI / Codex only — no slash command.

MCP setup and why codebase-memory-mcp installs separately

aicrew install wires MCP config files into each tool. It does not install the MCP server binaries — those are standalone programs that live on your machine, so each one is a one-time npm install -g (or auto-download). This separation keeps the aicrew package itself dependency-free and lets you install only the servers you want.

Server binaries (one-time, per machine)

npm install -g codebase-memory-mcp   # required for graph queries (~500 tok vs ~80K grep)
npm install -g token-optimizer-mcp   # optional; needed for the Cursor token-optimizer entry
# context-mode: no install needed — auto-downloads via npx on first use

Or run aicrew install mcp for the full checklist with paths.

How config is wired

| Tool | Target | Source in repo | |------|--------|----------------| | Claude Code | ~/.claude/.mcp.json (symlink) | config/mcp/claude.json | | Cursor | ~/.cursor/mcp.json (symlink) | config/mcp/cursor.local.json | | Codex | ~/.codex/config.toml (merged) | config/mcp/codex.toml |

Cursor secrets: config/mcp/cursor.json is the committed template (placeholders only). config/mcp/cursor.local.json is gitignored; install seeds it from the template and symlinks Cursor to it.

| Server | Role | Install | |--------|------|---------| | codebase-memory-mcp | Graph index of functions, classes, call chains, routes | npm install -g codebase-memory-mcp | | context-mode | Context shaping for long sessions | Auto via npx — no install needed | | token-optimizer-mcp | Token budgeting and cache-friendly responses (optional) | npm install -g token-optimizer-mcp |

The Cursor template also lists optional servers (GitHub, filesystem, memory, Brave, Playwright, SQLite, Postgres, GitKraken, Perplexity) — enable and fill env vars in cursor.local.json as needed. License notices for all wired servers: [THIRDPARTYNOTICES.md](THIRDPARTYNOTICES.md).

Full install reference

# one-off (no global binary)
npx aicrew install
npx aicrew update
npx aicrew status
npx aicrew agent-kit init ./agent-kit
npx aicrew cursor-plugin init ./cursor-multi-tool-plugin

# global CLI (from a git clone)
cd /path/to/aicrew && npm install -g .

If you see EACCES on Linux:

npm install -g --prefix ~/.local/npm-global .
export PATH="$HOME/.local/npm-global/bin:$PATH"   # add to ~/.bashrc

What install does: copies packaged skills into ~/Agents/ (shared source of truth); merges skills into ~/.claude/skills/ (adds missing files, never overwrites); symlinks ~/.claude/commands/*.md → ~/Agents/commands/*.md; merges codex-skills/ into ~/.codex/skills/; registers session-memory.py and security-guard.py in ~/.claude/settings.json; wires MCP config files. It does not install MCP server binaries.

Token economy and how savings work

> See also: [Pipeline overview](docs/pipeline-overview.md) — token foundation summary, Scout → verify, and command decision table.

A repo-wide grep can cost ~80,000 tokens and burns context fast on large codebases. aicrew routes every query to the cheapest strategy first: a codebase-memory-mcp graph query for "what calls authMiddleware?" costs ~500 tokens instead. Every entry-point command (/dev, /fix, /quick) carries the same token-saving foundation — only pipeline depth differs.

> Authoritative capability list: [skills/docs/token-foundation.md](./skills/docs/token-foundation.md) > Full guide with worked examples: [skills/docs/how-token-savings-work.md](./skills/docs/how-token-savings-work.md) > Scout → Act deep dive: [skills/docs/speculative-context.md](./skills/docs/speculative-context.md)

In short, the stack combines graph-first research, a speculative Scout → verify pass, layered guardrails, a context-economy read policy (diff/tree/search before whole-file reads), .ai/state checkpoints, /compact between phases, /handoff on tool switch, optional context-mode + token-optimizer-mcp, and terse-by-default output. See token-foundation.md for the per-capability savings figures.

When to use each lever

| You want to… | Use | |---|---| | Explore a large codebase without burning context | codebase-memory-mcp graph queries (all commands use this) | | Keep sessions from filling the context window | /lean on | | Compress stale context between phases | /compact at phase boundaries | | Hand off a session to a different tool | /handoff (~300 tokens) | | Scout-first with minimal overhead | /quick (Scout → Act) |

Use /lean off (aka /normal) to restore full verbosity.

Pipeline depth (the only thing that differs)

| Command | Phases | Use when | |---|---|---| | /dev | 9 (intake → research → brainstorm → design → implement → tests → security → audit → conclude) | Feature, refactor, or anything needing a design spec | | /fix | 5 (intake → bug analysis → implement → tests → security → conclude) | Bug fix with mandatory TDD | | /quick | 2 (Scout → Act) | Scoped task; graph-first without pipeline overhead |

Guardrails

aicrew uses a layered safety model. For the rail-by-rail mapping see [skills/docs/guardrails-taxonomy.md](./skills/docs/guardrails-taxonomy.md).

• Input rail: security-guard.py fires before every file write — blocks PEM private keys and AWS secrets outright; warns on high-entropy strings.
• Output rail: security-reviewer agent scans changed files in Phase 6 of /dev.
• Phase gates: every /dev and /fix phase stops and waits for your explicit go-ahead — the agent never invents your response.
• Session memory: session-memory.py strips … blocks before writing session journals.

| Script | Claude hook | Role | |--------|-------------|------| | session-memory.py | Stop | Session journal, optional batch typecheck, ` stripping | | security-guard.py` | PreToolUse (Edit / Write) | Blocks obvious secrets; warns on risky patterns |

Set ECC_HOOK_PROFILE to minimal, standard (default), or strict.

Benchmark and reports

aicrew benchmark --report

Writes .ai/reports/TOKEN_REPORT..md — baseline vs aicrew estimates for your codebase. All numbers are clearly labeled estimated.

Platform matrix and per-platform install

Every action is reachable from every supported platform. Full details live in the canonical docs:

> Complete action × platform matrix: [skills/docs/platform-entry-points.md](./skills/docs/platform-entry-points.md) > Step-by-step install per provider: [skills/docs/install-by-platform.md](./skills/docs/install-by-platform.md)

| Action | CLI | Claude Code / Cursor / Gemini / Antigravity | Codex | |--------|-----|---------------------------------------------|-------| | Full dev pipeline | — | /dev | aicrew-dev | | Fast bug fix | — | /fix | aicrew-fix | | Scout → Act | — | /quick | aicrew-quick | | Design brainstorm | — | /brainstorm | brainstorm | | First-time install | aicrew install | — | aicrew-install | | Pull latest skills | aicrew update | — | aicrew-update | | Check install state | aicrew status | — | aicrew-status |

> Setup actions (install, update, status, agent-kit, cursor-plugin) are CLI / Codex only — no slash command. /normal is an alias of /lean off.

Claude Code (aicrew install claude) — slash commands from ~/.claude/commands/ (symlinked from ~/Agents/commands/):

Daily:        /dev   /fix   /quick   /conclude   /brainstorm   /handoff   /session   /lean
Maintenance:  /update-skills   /harness-audit   /benchmark

Hooks auto-registered: session-memory.py (Stop) + security-guard.py (PreToolUse).

Codex (aicrew install codex) — skills land in ~/.codex/skills/:

aicrew-dev   aicrew-fix   aicrew-quick   aicrew-conclude   aicrew-update-skills
aicrew-harness-audit   aicrew-benchmark   brainstorm   lean
aicrew-install   aicrew-update   aicrew-status   aicrew-agent-kit   aicrew-cursor-plugin
aicrew-session   aicrew-handoff   aicrew-normal

Cursor (aicrew install cursor) — slash commands via Claude integration; rules from ~/Agents/agents/; MCP wired via ~/.cursor/mcp.json. Share .mdc rules with aicrew agent-kit init ./agent-kit; scaffold a multi-tool terminal panel with aicrew cursor-plugin init.

Gemini CLI (aicrew install gemini) — populates ~/Agents/ and prints config instructions.

Antigravity — reference ~/Agents/commands/ in your Antigravity config; slash commands work natively.

Where skills land

| Location | Contents | |---|---| | ~/Agents/ | Single source of truth — commands, agents, hooks, docs | | ~/.claude/commands/ | Symlinks → ~/Agents/commands/*.md (slash commands) | | ~/.codex/skills/ | Codex-native skill folders (aicrew-dev, aicrew-fix, …) | | ~/.claude/settings.json | Merged hook entries (session-memory.py, security-guard.py) | | ~/.cursor/mcp.json | Symlink → config/mcp/cursor.local.json | | ~/.codex/config.toml | Patched with MCP server entries |

~/Agents/                 # merged from package skills/ — commands, agents, hooks, docs, bin/
~/.claude/commands/       # symlinks → ~/Agents/commands/*.md
~/.claude/skills/         # merged copy of Claude-facing skills
~/.claude/settings.json   # merged hook entries
~/.codex/skills/          # merged Codex skill packages

[your-repo]/
  .ai/skills/             # optional project overrides (version-controlled)
  .ai/state/              # optional session checkpoints
  .cursor/rules/          # optional; or symlinks from agent-kit

CLI reference

| Command | Codex skill | Claude Code | Purpose | |---------|-------

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: AKSoftCode
• Source: AKSoftCode/aicrew
• License: MIT
• Homepage: https://github.com/AKSoftCode/aicrew

Install and usage instructions live in the source repository linked above.