{"id":50956168,"url":"https://github.com/heretyc/subagent-mcp","last_synced_at":"2026-06-18T07:01:39.715Z","repository":{"id":362153775,"uuid":"1253519762","full_name":"Heretyc/subagent-mcp","owner":"Heretyc","description":"Min-Max every agent. Simplify every session.","archived":false,"fork":false,"pushed_at":"2026-06-10T16:14:17.000Z","size":1407,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-10T16:23:11.068Z","etag":null,"topics":["agentic","ai","ai-agents","claude-code-plugin","claude-plugin","codex-app","codex-plugin","mcp"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Heretyc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-29T14:47:51.000Z","updated_at":"2026-06-10T15:44:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Heretyc/subagent-mcp","commit_stats":null,"previous_names":["heretyc/subagent-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Heretyc/subagent-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Heretyc%2Fsubagent-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Heretyc%2Fsubagent-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Heretyc%2Fsubagent-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Heretyc%2Fsubagent-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Heretyc","download_url":"https://codeload.github.com/Heretyc/subagent-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Heretyc%2Fsubagent-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34479555,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-18T02:00:06.871Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic","ai","ai-agents","claude-code-plugin","claude-plugin","codex-app","codex-plugin","mcp"],"created_at":"2026-06-18T07:01:38.690Z","updated_at":"2026-06-18T07:01:39.710Z","avatar_url":"https://github.com/Heretyc.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# subagent-mcp\n\nMCP server that launches and manages always-interactive Claude Code and Codex sub-agent sessions. Runs on **macOS, Linux, and Windows**.\n\n**No direct API calls.** subagent-mcp does NOT use the Anthropic or OpenAI HTTP APIs and has no plans to. Claude sessions use the Claude Agent SDK against your local Claude Code executable; Codex sessions use your local `codex app-server`. No API keys.\n\n**License:** Apache-2.0 | **Author:** Lexi Blackburn | **Repo:** https://github.com/Heretyc/subagent-mcp\n\n---\n\n## Features\n\n- Start Claude or Codex interactive sessions as managed sub-agents from any MCP host\n- Poll status, stream stdout/stderr tails, and enqueue follow-up messages to live sessions\n- 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)\n- Liveness tracking via the visible provider stream (Claude SDK events, Codex app-server 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\n- Ultracode mode for Opus 4.8 -- headless activation via `--settings {\"ultracode\":true}` (see [docs/usage.md](docs/usage.md))\n- 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\n- stdio MCP transport; built with `@modelcontextprotocol/sdk` + `zod`\n- `orchestration-mode` tool — toggles orchestrator directives injected by bundled Claude Code / Codex hooks; Claude also gets a deterministic `PreToolUse` gate (Desktop hosts toggle but do not inject); see [docs/spec/orchestration-mode/_INDEX.md](docs/spec/orchestration-mode/_INDEX.md)\n\n---\n\n## Quick Start\n\n**Prerequisites:** Node.js \u003e= 18, plus the `claude` and/or `codex` CLIs installed globally and authenticated.\n\nInstalled via [GitHub Packages](https://github.com/Heretyc/subagent-mcp/pkgs/npm/subagent-mcp). One-time `.npmrc` setup required (GitHub Packages requires auth even for public packages):\n\n```bash\n# 1. Configure registry for @heretyc scope (once per machine)\necho \"@heretyc:registry=https://npm.pkg.github.com\" \u003e\u003e ~/.npmrc\n\n# 2. Authenticate — use a classic PAT with read:packages scope\necho \"//npm.pkg.github.com/:_authToken=YOUR_GITHUB_PAT\" \u003e\u003e ~/.npmrc\n\n# 3. Install and wire\nnpm install -g @heretyc/subagent-mcp\nsubagent-mcp setup\n```\n\n`setup` detects which vendors are present, registers the MCP server, and writes orchestration-mode hooks. Idempotent — safe to re-run after updates. Pass `--dry-run` to preview.\n\nFor consumer projects, run `subagent-mcp init --root /path/to/project` to upsert\nthe managed invariant block into `AGENTS.md`, `CLAUDE.md`, and `GEMINI.md`.\nUse `--dry-run` to preview, `--remove` to uninstall the block, and `--force`\nonly if you intentionally run inside this source repo.\n\nTo install the block into the providers' **official global user-config files**\ninstead — `~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, `~/.gemini/GEMINI.md` —\nrun `subagent-mcp init --global`. It honors `--dry-run`/`--remove`/`--force`\nand is mutually exclusive with `--root`/`--files`/`--copilot`/`--cursor`. See\n[docs/registration.md](docs/registration.md).\n\nAfter setup, restart your Claude Code or Codex session. On Codex, run `/hooks` and trust the new hook.\n\n**Updating:** `subagent-mcp update \u0026\u0026 subagent-mcp setup`\n\nFor manual wiring, developer install from source, Gemini CLI, and Claude Desktop, see [docs/registration.md](docs/registration.md).\n\n---\n\n## Auto Mode\n\n`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.\n\n`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`.\n\n**task_category** (required) — pick one:\n\n| Category | What it is |\n|---|---|\n| `math_proof` | deliverable is a proof/derivation/formally-checkable result |\n| `security_review` | security verdict, threat assessment, or demonstrated exploit |\n| `debugging` | verified fix/root-cause; requires an observed failure as precondition |\n| `quality_review` | evaluative verdict on existing artifact (review, A-vs-B, validate-vs-spec) |\n| `architecture` | cross-module design/plan, no code, no execution loop |\n| `agentic_execution` | end-state via act/observe/adapt loop (run/deploy/provision/browse) |\n| `data_analysis` | empirical finding about structured dataset (query, stat, model) |\n| `coding` | bounded runnable code artifact, one-pass (implement, test, refactor) |\n| `knowledge_synthesis` | novel integrated prose over sources (synthesize, summarize, draft) |\n| `mechanical` | deterministic single-pass transform, exact-match checkable (grep, rename, reformat) |\n| `prompt_engineering` | designed/optimized prompt or prompt-system steering an LLM/agent (composite-inferred) |\n| `vulnerability_research` | discovery + PoC of a novel vulnerability (composite-inferred) |\n| `molecular_biology` | reasoned molecular/computational-biology result over sequences, structures, or -omics data (composite-inferred) |\n| `ml_accelerator_design` | hardware/software design for ML acceleration — dataflow, kernel, roofline (composite-inferred) |\n| `fallback_default` | no category matches with confidence; prefer splitting work instead |\n\nThe last four are **composite-inferred**: they carry no dedicated benchmark and their routing competency is composed from parent categories rather than measured directly.\n\n**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.\n\n---\n\n## Tools\n\nSix tools are exposed over the stdio MCP transport:\n\n| Tool | Purpose |\n|------|---------|\n| `launch_agent` | Start a new `claude`/`codex` sub-agent session |\n| `poll_agent` | Get status + output tail of one agent |\n| `kill_agent` | Immediately force-kill any live agent |\n| `send_message` | Enqueue a user message on a live session |\n| `list_agents` | List all agents with token-efficient core metrics |\n| `wait` | Block until one or more agents finish, or 15-minute timeout |\n\nFull 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](docs/tools.md).\n\n---\n\n## Agent Lifecycle\n\nEach agent transitions through these states:\n\n| Status | Meaning |\n|--------|---------|\n| `processing` | Driver alive with a visible provider-stream heartbeat in the last 10 minutes -- actively working. Launch time counts as the initial heartbeat |\n| `stalled` | Driver STILL ALIVE but no parsed visible provider stream item for \u003e= 10 minutes -- working, thinking, or awaiting a temp-file handoff (not a failure). Recovers to `processing` if the visible stream resumes |\n| `finished` | Current turn completed, or driver exited with code 0 |\n| `errored` | Process exited with non-zero code |\n| `stopped` | Terminated by `kill_agent` |\n\n`processing` and `stalled` are live. `finished` is reportable for `wait`; if `alive` is still true, `send_message` can start the next turn on the same session. A health monitor runs every 10 seconds, and `poll_agent`/`list_agents` additionally reconcile driver exit synchronously. `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 over `kill_agent`. Full semantics: [docs/reference/status-lifecycle.md](docs/reference/status-lifecycle.md).\n\n---\n\n## Documentation\n\n- [docs/registration.md](docs/registration.md) -- per-platform registration (Claude Code, Codex, Gemini), prerequisites, install, config paths.\n- [docs/tools.md](docs/tools.md) -- full Tool Reference for all six tools, including `alive` / `idle_seconds` / `hint` fields.\n- [docs/usage.md](docs/usage.md) -- model \u0026 effort matrix, ultracode mechanism, underlying CLI invocations, usage examples.\n- [docs/SPEC.md](docs/SPEC.md) -- full technical specification (architecture, schemas, status lifecycle, error catalogue).\n- [docs/spec/interactive-drivers.md](docs/spec/interactive-drivers.md) -- always-interactive Claude/Codex driver model.\n- [docs/release-notes.md](docs/release-notes.md) -- operator-facing release notes (current: **v2.9.0**).\n\n---\n\n## License\n\nApache-2.0 -- Copyright 2026 Lexi Blackburn\n\nSee [docs/SPEC.md](docs/SPEC.md) for the full technical specification.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheretyc%2Fsubagent-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fheretyc%2Fsubagent-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheretyc%2Fsubagent-mcp/lists"}