convez.ai
MCP ServerAutomaçãoAvançado
Heretyc

Subagent MCP

Heretyc/subagent-mcp

Orquestre múltiplos agentes Claude/Codex localmente sem APIs externas

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que executa e gerencia processos de sub-agentes Claude e Codex locais como processos filhos. Permite orquestração de múltiplos agentes de IA sem chamadas diretas a APIs, com gerenciamento de concorrência, rastreamento de liveness e modo ultracode para Opus 4.8.

Instalação

$npx convez-ai Heretyc/subagent-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
71%
Último commit
há 1 semana
Versão
v3.2.4
Issues abertas
27
Contribuidores
2

Casos de uso

  • Orquestração de múltiplos agentes de IA para tarefas complexas
  • Automação de workflows que requerem colaboração entre diferentes modelos
  • Desenvolvimento de sistemas multi-agente sem dependência de APIs externas

Veredito

Ferramenta especializada para arquitetos de sistemas multi-agente que precisam de controle fino sobre orquestração local. Requer pré-requisitos técnicos significativos (CLIs instaladas, autenticação, Node.js) e é mais adequada para cenários avançados de automação complexa.

README

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

subagent-mcp

MCP server that launches and manages locally installed claude and codex CLI binaries as child sub-agent processes. Runs on macOS, Linux, and Windows.

No direct API calls. subagent-mcp does NOT use the Anthropic or OpenAI HTTP APIs and has no plans to. It invokes your locally installed and authenticated claude (Claude Code) and codex CLIs. No API keys, no SDKs beyond the CLIs themselves.

License: Apache-2.0 | Author: Lexi Blackburn | Repo: https://github.com/Heretyc/subagent-mcp


Features

  • Spawn claude or codex CLI processes as managed sub-agents from any MCP host
  • Poll status, stream stdout/stderr tails, and send stdin messages to live agents
  • Concurrency caps: 5 concurrent Claude agents + 5 concurrent Codex agents (counts only actively-streaming processing agents, to limit API rate-limit pressure; quiet stalled agents don't reserve a slot)
  • Liveness tracking via the visible provider stream (Claude stream-json, Codex --json JSONL): agents with no parsed visible provider stream item for 10 minutes enter stalled state (still alive, just quiet -- thinking or awaiting a temp-file handoff), and recover to processing if the visible stream resumes
  • Ultracode mode for Opus 4.8 -- headless activation via --settings {"ultracode":true} (see docs/usage.md)
  • Cross-platform exe resolution (Windows: npm-prefix .exe paths; macOS/Linux: PATH + Homebrew/usr-local fallbacks); immediate taskkill /t /f (Windows) / SIGKILL (POSIX) force-kill; no graceful shutdown period
  • stdio MCP transport; built with @modelcontextprotocol/sdk + zod
  • orchestration-mode tool — toggles an orchestrator-only directive that the bundled Claude Code / Codex plugin injects every turn via its UserPromptSubmit hook (Desktop hosts toggle but do not inject); see docs/spec/orchestration-mode/_INDEX.md

Quick Start

Prerequisites: Node.js >= 18, plus the claude and/or codex CLIs installed globally and authenticated.

Installed via GitHub Packages. One-time .npmrc setup required (GitHub Packages requires auth even for public packages):

# 1. Configure registry for @heretyc scope (once per machine)
echo "@heretyc:registry=https://npm.pkg.github.com" >> ~/.npmrc

# 2. Authenticate — use a classic PAT with read:packages scope
echo "//npm.pkg.github.com/:_authToken=YOUR_GITHUB_PAT" >> ~/.npmrc

# 3. Install and wire
npm install -g @heretyc/subagent-mcp
subagent-mcp setup

setup detects which vendors are present, registers the MCP server, and writes the UserPromptSubmit hook for orchestration-mode injection. Idempotent — safe to re-run after updates. Pass --dry-run to preview.

After setup, restart your Claude Code or Codex session. On Codex, run /hooks and trust the new hook.

Updating: npm install -g @heretyc/subagent-mcp && subagent-mcp setup

For manual wiring, developer install from source, Gemini CLI, and Claude Desktop, see docs/registration.md.


Auto Mode

launch_agent supports auto mode: pass prompt + task_category and the server picks the best provider/model/effort for that category from its routing table, silently falling back to the next-best candidate on any launch-time failure.

provider, model, and effort are optional overrides — omit them to get auto-selected best combination. Rules: passing model requires provider; passing effort requires both provider and model.

task_category (required) — pick one:

CategoryWhat it is
math_proofdeliverable is a proof/derivation/formally-checkable result
security_reviewsecurity verdict, threat assessment, or demonstrated exploit
debuggingverified fix/root-cause; requires an observed failure as precondition
quality_reviewevaluative verdict on existing artifact (review, A-vs-B, validate-vs-spec)
architecturecross-module design/plan, no code, no execution loop
agentic_executionend-state via act/observe/adapt loop (run/deploy/provision/browse)
data_analysisempirical finding about structured dataset (query, stat, model)
codingbounded runnable code artifact, one-pass (implement, test, refactor)
knowledge_synthesisnovel integrated prose over sources (synthesize, summarize, draft)
mechanicaldeterministic single-pass transform, exact-match checkable (grep, rename, reformat)
fallback_defaultno category matches with confidence; prefer splitting work instead

Atomic-split guidance: if you are unsure which category fits, do NOT submit one large amorphous task. Break the work into smaller atomic steps each mapping to a single category and launch one agent per step.


Tools

Six tools are exposed over the stdio MCP transport:

ToolPurpose
launch_agentSpawn a new claude/codex sub-agent process
poll_agentGet status + output tail of one agent
kill_agentImmediately force-kill any live agent
send_messageWrite to a live agent's stdin
list_agentsList all agents with token-efficient core metrics
waitBlock until one or more agents finish, or 15-minute timeout

Full parameters, return shapes, the alive / idle_seconds / hint / recent_stream fields, and poll_agent's last-3 visible-stream items are in docs/tools.md.


Agent Lifecycle

Each agent transitions through these states:

StatusMeaning
processingProcess alive with a visible provider-stream heartbeat in the last 10 minutes -- actively working. Launch time counts as the initial heartbeat
stalledProcess STILL ALIVE but no parsed visible provider stream item for >= 10 minutes -- working, thinking, or awaiting a temp-file handoff (not a failure). Recovers to processing if the visible stream resumes
finishedProcess exited with code 0, or Codex emitted turn.completed event
erroredProcess exited with non-zero code
stoppedTerminated by kill_agent

Only finished, errored, and stopped are terminal; processing and stalled are live. A health monitor runs every 10 seconds, and poll_agent/list_agents additionally reconcile exit synchronously so an exited process is reported immediately. wait does not return just because an agent is stalled. stalled agents recover to processing if the visible stream resumes and are never auto-killed -- prefer wait/re-poll (or checking the agent's temp output) over kill_agent. Full semantics: docs/reference/status-lifecycle.md.


Documentation

  • docs/registration.md -- per-platform registration (Claude Code, Codex, Gemini), prerequisites, install, config paths.
  • docs/tools.md -- full Tool Reference for all six tools, including alive / idle_seconds / hint fields.
  • docs/usage.md -- model & effort matrix, ultracode mechanism, underlying CLI invocations, usage examples.
  • docs/SPEC.md -- full technical specification (architecture, schemas, status lifecycle, error catalogue).

License

Apache-2.0 -- Copyright 2026 Lexi Blackburn

See docs/SPEC.md for the full technical specification.

Ver o original no GitHub

Bom para

Relacionados