convez.ai
MCP ServerAutomaçãoAvançado
chasenstark

Crew MCP – Orquestrador de Múltiplos Agentes IA

chasenstark/crew-mcp

Orquestre múltiplos agentes IA em worktrees isoladas, sem API keys adicionais

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que transforma sua CLI de codificação IA em capitã de uma tripulação multi-agente. Dispache trabalho para Claude Code, Codex, Gemini ou modelos locais, cada execução isolada em sua própria git worktree, sem poluir seu diretório de trabalho.

Instalação

$npx convez-ai chasenstark/crew-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
3
Forks
2
Acompanhando
0
Saúde
42%
Último commit
há 2 semanas
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Implementação paralela de features por diferentes modelos IA
  • Review panels com múltiplos agentes avaliando código simultaneamente
  • Iteração automática até critérios de aceição serem atendidos
  • Uso de modelos locais (Ollama, LM Studio) junto com CLIs na nuvem
  • Fluxo de código ship-quality com revisão multi-agente gateada

Veredito

Crew-MCP é uma arquitetura sofisticada para orquestração de múltiplos agentes IA em contexto de desenvolvimento, eliminando API keys adicionais ao aproveitar CLIs já instaladas. Excelente para equipes que buscam workflows de code review automatizados e iteração de qualidade, mas demanda compreensão profunda de git workflows e configuração de múltiplos agentes.

README

A tradução para o português deste README ainda está na fila.

🚢 crew-mcp

An MCP server that turns your AI coding CLI into the orchestrator of a multi-agent crew. Dispatch work to Claude Code, Codex, Gemini CLI, or local models — each run gets its own git worktree, so your working directory stays clean and merges happen only when you say so.

💡 The vision — no API keys, just the CLIs you already have

Crew drives the AI coding CLIs you've already installed and logged in. Every dispatched run goes through Claude Code, Codex, or Gemini on your existing subscription — 🔑 no API keys to wrangle, 💸 no per-token billing, no second bill for the same models. Want it fully private? 🏠 Add local models (Ollama, LM Studio) and those runs never leave your machine.

That's the whole idea: a multi-agent crew built on the plans you're already paying for. 🤝

you ── Claude Code (captain) ──┬── run_agent → Codex (worktree A)
                                ├── run_agent → Gemini (worktree B)
                                └── run_panel → Claude + Codex (parallel review)

⚡ Quickstart

Once installed (see 📦 Install below), just talk to your host CLI:

have Codex implement the rate limiter and review it until the tests pass

The captain derives acceptance criteria, dispatches Codex into an isolated worktree, runs review, folds the findings back, and asks before merging — all while you stay in one conversation.

Prefer to drive explicitly? Name the agent ("send this to Gemini"), ask for a panel ("have Claude and Codex both review this"), or kick off the ship-quality loop directly with /crew-iterate.

🧭 How it works

Crew installs two things into your host CLI:

  1. An MCP server exposing orchestration tools (run_agent, run_panel, merge_run, etc.)
  2. Captain skills — markdown playbooks that teach the host LLM how to orchestrate. The umbrella crew skill covers dispatch, review panels, and merge; the crew-iterate skill drives a criteria-gated implement → review → iterate loop (see 🔁 The crew-iterate skill below).

Your host CLI's LLM becomes the captain. You stay in one conversation. When work needs another agent, the captain dispatches it into an isolated worktree and reports back.

✨ What you can do

  • Dispatch work — "have Codex implement this feature", "send this to Claude for review". The captain picks the right agent, allocates a worktree, and dispatches.
  • Run review panels — multiple models review the same diff in parallel. Each model does a full independent review; the captain cross-checks agreement and disagreement across models.
  • Iterate to acceptance — define acceptance criteria, then loop between an implementer and one or more reviewers until every criterion passes. The captain drives the loop; you watch or intervene. See 🔁 The crew-iterate skill below.
  • Use local models — add Ollama, LM Studio, or any OpenAI-compatible endpoint as a crew agent alongside the cloud CLIs.
  • Merge when ready — review the diff, then merge_run applies it to your branch. Or discard_run to throw it away. Nothing touches your working tree until you decide.

🔁 The crew-iterate skill

For work you want pushed to ship-quality, crew-iterate runs a criteria-gated loop instead of a one-shot dispatch.

Trigger it by intent — "keep working on X with review", "iterate until it's good", "ship-quality loop" — or invoke it directly: /crew-iterate on Claude Code (crew-iterate on Codex / Gemini).

The loop:

  1. Derive acceptance criteria from your request and confirm them with you. They become the contract for every downstream step.
  2. Confirm agents — the captain proposes an implementer and a reviewer count scaled to the change's complexity (one reviewer for a narrow change, up to three distinct models for large or high-risk ones), honoring your configured defaults and bans. You OK or adjust.
  3. Dispatch the implementer with the criteria embedded in the prompt.
  4. Dual review — a free inline review by the captain plus one or more dispatched reviewers, each scoring every criterion PASS/FAIL and giving an overall verdict. Multiple reviewers run as a parallel panel.
  5. Iterate — failing criteria and findings fold back via continue_run until every criterion passes and every reviewer approves (bounded by a safety cap).
  6. Merge — on your explicit go, the run is squash-merged into a single clean commit.

Set persistent defaults so you don't re-pick every run — a default implementer, default reviewers, and a per-scope ban list (e.g. "never use Gemini"):

crew-mcp config   # → "Agent defaults…"

📋 Requirements

  • Node.js ≥ 20
  • git (worktrees are how runs stay isolated)
  • At least one host CLI — Claude Code, Codex CLI, or Gemini CLI — installed and authenticated. Local models (Ollama, LM Studio, …) work too.

📦 Install

npm install -g crew-mcp

Or from source:

git clone https://github.com/chasenstark/crew-mcp.git
cd crew-mcp
npm install && npm run build && npm link

Install into your host CLI:

crew-mcp install --target claude-code   # Claude Code
crew-mcp install --target codex         # OpenAI Codex CLI
crew-mcp install --target gemini        # Gemini CLI
crew-mcp install --target all           # auto-detect installed hosts

Verify the install:

crew-mcp verify

Restart your host CLI session. The mcp__crew__* tools and the captain skill are now available.

Project-scoped install

For a shared repo, commit portable host config and skills once:

npm install --save-dev crew-mcp
npx crew-mcp install --scope project --target claude-code,codex
git add .mcp.json .claude .codex .crew/install.project.json package.json package-lock.json

Project scope writes ./node_modules/.bin/crew-mcp serve into the host config, not a machine-specific dist/index.js or home-directory path. It also writes .crew/install.project.json with repo-relative paths, does not write ~/.crew/install.json, and does not seed ~/.crew/agents.json.

After pulling the repo, each developer runs:

npm install

Claude Code reads .mcp.json and .claude/skills from the project. Codex developers must trust the repo once before .codex/config.toml is loaded:

[projects."/absolute/path/to/repo"]
trust_level = "trusted"

Then restart the host and run:

npx crew-mcp verify --scope project

Per-machine agent overrides still use crew-mcp agents add or crew-mcp agents edit.

🤖 Add local models

crew-mcp agents add --provider ollama
crew-mcp agents add --provider lm-studio
crew-mcp agents add --provider openai-compatible --api-base http://localhost:8080/v1

The interactive wizard discovers available models and registers them as crew agents.

🖥️ Optional: live tail handler (macOS)

Dispatched runs log to ~/.crew/runs/<id>/. Install the crew-tail:// URL handler to open a side Terminal window with live logs automatically:

crew-mcp install-tail-handler

Without it, the captain prints a tail -F command you can run manually.

🧹 Uninstall

Removes the crew MCP block and skills from a host CLI (your runs and config under ~/.crew/ are left untouched):

crew-mcp uninstall --target claude-code
crew-mcp uninstall --target all

🧰 MCP tools

ToolPurpose
run_agentDispatch work to a specific agent in an isolated worktree
run_panelDispatch parallel reviewers (full-review-per-model)
aggregate_panelCollect panel reviewer findings
get_panel_statusCheck panel progress
get_run_statusCheck a single run's status
list_runsList all runs, optionally filtered by status
list_agentsList available agents with useWhen, strengths, defaults, and health
merge_runApply a completed run's changes to your branch
continue_runSend follow-up instructions to a running agent
discard_runDiscard a run's worktree and changes
cancel_runCancel a running agent
get_crew_preferencesRead crew configuration

⚙️ Configure

crew-mcp config

Interactive TUI for per-machine settings:

  • notifications.success / error — OS notifications when dispatched runs finish (on by default)
  • confirmBeforeMerge — require explicit confirmation before merge_run mutates your branch (on by default)
  • Agent defaults — default implementer and reviewers for crew-iterate, default reviewers for run_panel, and per-scope ban lists. Stored globally in ~/.crew/workflow.yaml; the toggles above live in ~/.crew/config.json.

Env overrides: CREW_OS_NOTIFICATIONS=off, CREW_CONFIRM_BEFORE_MERGE=off.

Crew garbage-collects terminal runs under ~/.crew/runs/ so worktree checkouts don't pile up: a terminal run's worktree is reclaimed after the worktree window (default 7d, branch kept unless the run was merged) and its run-dir deleted after the run-dir window (default 30d). The GC runs at server startup; run it on demand with crew-mcp cleanup (--dry-run to preview, --all-repos to sweep every repo). Tune the windows in crew-mcp config → Cleanup & retention (stored in config.json as cleanup.worktreeTtlDays / cleanup.runDirTtlDays; -1 = off). Env vars CREW_WORKTREE_TTL_DAYS / CREW_RUNDIR_TTL_DAYS (accept off) override config for a given process.

👥 Managing agents

Agents live in ~/.crew/agents.json. Each entry can carry useWhen primary routing prose, strengths secondary tags, a default effort, and a model — the captain reads these to route work when you don't name an agent explicitly.

crew-mcp agents add      # register a model (interactive wizard, --use-when supported)
crew-mcp agents edit     # tune useWhen / strengths / effort / model
crew-mcp agents remove   # drop an agent

The add wizard also discovers local models — see 🤖 Add local models above.

Built-in strength tags come from a curated vocabulary: deep-reasoning, code-review, refactoring, technical-writing, fast-iteration, autonomous-loops, bulk-implementation, long-context, codebase-triage, and multimodal. Custom tags remain valid; the curated list is only the default picker and seed set.

🔌 Supported hosts

HostAdapterInstall target
Claude Codeclaude-code--target claude-code
Codex CLIcodex--target codex
Gemini CLIgemini-cli--target gemini
Ollama / LM Studio / vLLMopenai-compatiblecrew-mcp agents add
Any CLI with a command interfacegenericcrew-mcp agents add

🩺 Troubleshooting

mcp__crew__* tools don't show up. Restart your host CLI session after install — the MCP server is loaded at startup. Then run crew-mcp verify to confirm the config block and skills are in place.

The captain says crew may be misconfigured. Re-run crew-mcp install --target <host> and restart the session. crew-mcp verify reports exactly which host is missing the MCP block or skill.

Gemini warns about a skill conflict. Harmless if it persists, but re-running crew-mcp install --target gemini resolves duplicate skill copies (Gemini also reads the shared ~/.agents/skills/ directory).

A run is stuck or unwanted. crew-mcp exposes cancel_run (stop a running agent) and discard_run (throw away its worktree); ask the captain, or inspect runs under ~/.crew/runs/.

🏗️ Architecture

┌─────────────────────────────────────────────┐
│  Host CLI (Claude Code / Codex / Gemini)    │
│  ┌───────────────────────────────────────┐  │
│  │  Captain skill (markdown playbook)    │  │
│  └──────────────┬────────────────────────┘  │
│                 │ MCP tool calls             │
│  ┌──────────────▼────────────────────────┐  │
│  │  crew-mcp server (stdio transport)    │  │
│  │  ┌────────────┐  ┌────────────────┐   │  │
│  │  │ Dispatcher │  │ Run state      │   │  │
│  │  │ (worktree  │  │ (status, logs, │   │  │
│  │  │  + adapter │  │  peer messages │   │  │
│  │  │  + tool    │  │  panel state)  │   │  │
│  │  │  loop)     │  │                │   │  │
│  │  └─────┬──────┘  └────────────────┘   │  │
│  └────────┼──────────────────────────────┘  │
└───────────┼─────────────────────────────────┘
            │ spawns
  ┌─────────▼──────────┐
  │  Worker agent       │
  │  (own process,      │
  │   isolated worktree │
  │   under ~/.crew/)   │
  └─────────────────────┘

Each dispatched run gets a worktree at ~/.crew/runs/<runId>/worktree/. The host repo's working directory is never touched. merge_run squash-merges the run's branch into the host branch as a single commit.

📄 License

MIT

Ver o original no GitHub

Bom para

Relacionados