# Aicrew

> TDD-first AI dev pipeline for Claude Code, Cursor, Codex, Gemini CLI & Antigravity. /dev /fix /quick + token-saving hooks. npx aicrew install

- **Type:** MCP server
- **Install:** `agentstack add mcp-aksoftcode-aicrew`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [AKSoftCode](https://agentstack.voostack.com/s/aksoftcode)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [AKSoftCode](https://github.com/AKSoftCode)
- **Source:** https://github.com/AKSoftCode/aicrew
- **Website:** https://github.com/AKSoftCode/aicrew

## Install

```sh
agentstack add mcp-aksoftcode-aicrew
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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)

```bash
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)

```bash
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: [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

### Full install reference

```bash
# 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:

```bash
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

```bash
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](https://github.com/AKSoftCode)
- **Source:** [AKSoftCode/aicrew](https://github.com/AKSoftCode/aicrew)
- **License:** MIT
- **Homepage:** https://github.com/AKSoftCode/aicrew

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-aksoftcode-aicrew
- Seller: https://agentstack.voostack.com/s/aksoftcode
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.