Super Subagents

Quick Navigation

Get Started • Why Super Subagents • Tools • Companion Tools • Notifications • Templates • Configuration • Examples

Related MCP server: Containerized Strands Agents

The Pitch

AI coding assistants work one task at a time. You ask it to refactor a module, and you wait. Then you ask it to write tests, and you wait again. Then you ask it to update the docs. Super Subagents multiplies your AI coding bandwidth. Instead of sequential requests, spawn N agents that work simultaneously -- each with full tool access (file read/write, terminal, search) in its own isolated session. Three execution backends (OpenAI Codex, GitHub Copilot, Claude Agent SDK) with automatic failover.

⚡ Parallel Agents

Spawn unlimited sessions. Each agent gets its own workspace, tools, and execution context.

🔗 Task Dependencies

Chain tasks with depends_on. Coder waits for planner. Tester waits for coder.

🔄 Auto-Rotation

Multi-account PAT rotation. Seamless mid-session recovery on 429/5xx errors.

🎭 Agent Templates

Specialized system prompts for coding, planning, research, and testing.

How It Works

You (main session):  "Spawn three tasks: refactor auth, write API tests, update the migration guide"

→ brave-tiger-42:    Refactoring auth module...          [running]
→ calm-falcon-17:    Writing API integration tests...    [running]
→ swift-panda-88:    Updating migration guide...         [running]

You:                 Continue working on other things — or spawn more tasks.

Each agent runs as an autonomous session in the background. When it finishes, you get proactively notified — no polling needed. If it hits a rate limit, it rotates to another GitHub account automatically. Task IDs are human-readable (brave-tiger-42, calm-falcon-17) so you can track them at a glance.

Why Super Subagents

Get Started

Option 1: One-line install (recommended)

# Claude Desktop
npx install-mcp mcp-supersubagents --client claude-desktop

# Claude Code CLI
npx install-mcp mcp-supersubagents --client claude-code

# Cursor
npx install-mcp mcp-supersubagents --client cursor

# VS Code / Copilot
npx install-mcp mcp-supersubagents --client vscode

# Other clients: windsurf, cline, roo-cline, goose, zed, opencode, warp, codex, aider, gemini-cli
npx install-mcp mcp-supersubagents --client <client-name>

With environment variables for PAT tokens:

npx install-mcp mcp-supersubagents --client claude-desktop \
  --header "GITHUB_PAT_TOKENS: ghp_token1,ghp_token2"

Option 2: Manual config

Add to your MCP client configuration:

File: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "super-agents": {
      "command": "npx",
      "args": ["-y", "mcp-supersubagents"],
      "env": {
        "GITHUB_PAT_TOKENS": "ghp_token1,ghp_token2"
      }
    }
  }
}

claude mcp add super-agents -- npx -y super-subagents

Set your PAT tokens as environment variables before launching:

export GITHUB_PAT_TOKENS="ghp_token1,ghp_token2"

File: .cursor/mcp.json in your project root

{
  "mcpServers": {
    "super-agents": {
      "command": "npx",
      "args": ["-y", "mcp-supersubagents"],
      "env": {
        "GITHUB_PAT_TOKENS": "ghp_token1,ghp_token2"
      }
    }
  }
}

No build step required -- npx runs the package directly.

Note: GitHub PAT tokens with Copilot access are recommended but not required. Without PATs, tasks automatically fall back to the Claude Agent SDK (requires claude CLI). For rate-limit resilience, configure multiple tokens via GITHUB_PAT_TOKENS. See Multi-Account Rotation for details.

Tool Reference

Super Subagents exposes 8 MCP tools: 5 specialized launchers + 3 utility tools.

Launch Tools

All 5 launch tools share these parameters:

Per-tool details:

• launch-super-coder — Implementation tasks. Min 1000-char prompt + min 1 .md context file. Include: OBJECTIVE, FILES, CRITERIA, CONSTRAINTS, PATTERNS.

• launch-super-planner — Architecture/planning. Min 300-char prompt. Always uses claude-opus-4.6. Include: PROBLEM, CONSTRAINTS, SCOPE, OUTPUT.

• launch-super-researcher — Investigation. Min 200-char prompt. Include: TOPIC, QUESTIONS, HANDOFF TARGET.

• launch-super-tester — QA/testing. Min 300-char prompt + min 1 context file. Include: WHAT BUILT, FILES, CRITERIA, TESTS, EDGE CASES.

• launch-classic-agent — General-purpose agent. Min 200-char prompt. Use when a task doesn't fit the specialized roles.

{
  "prompt": "Refactor the auth module to use JWT refresh tokens. Read /src/services/auth.ts for current implementation...",
  "context_files": [{ "path": "/path/to/plan.md" }],
  "labels": ["backend", "auth"]
}

Recommended workflow: researcher → planner → coder → tester. Chain with depends_on.

message-agent

Send a follow-up message to a completed, failed, cancelled, rate-limited, or timed-out task's session. Resumes the same session so the agent retains full context of what it did.

{ "task_id": "brave-tiger-42", "message": "Now add unit tests for the changes you made" }

cancel-agent

Cancel one task, multiple tasks, or all tasks. Running/pending/waiting/rate-limited tasks are killed (SIGTERM). Completed/failed tasks are removed from memory. Duplicate IDs in an array are deduplicated automatically.

// Cancel one
{ "task_id": "brave-tiger-42" }

// Cancel many
{ "task_id": ["brave-tiger-42", "calm-falcon-17"] }

// Clear all
{ "task_id": "all", "clear": true, "confirm": true }

answer-agent

Respond when an agent asks a question via ask_user. The task pauses until you answer.

{ "task_id": "brave-tiger-42", "answer": "2" }
{ "task_id": "brave-tiger-42", "answer": "CUSTOM: Use TypeScript instead" }

Resources

All status and monitoring is done through MCP resources (not polling):

The server also implements the MCP Task primitive. Use tasks/result to retrieve filtered output. isError is true for any non-completed status (failed, cancelled, timed out, etc.):

→ tasks/result { taskId: "brave-tiger-42" }
← { content: [{ type: "text", text: "..." }], isError: false }

Two-Tier Output

Output is split into two tiers to minimize token costs for callers:

This means ~90% fewer tokens when reading task results via MCP, while full verbose output remains available in the file for debugging.

Clients can subscribe to resource URIs for real-time change notifications (debounced to max 1/sec per task). Each task also writes a live output file you can tail -f:

tail -f .super-agents/brave-tiger-42.output    # Follow live
tail -20 .super-agents/brave-tiger-42.output   # Last 20 lines

Agent Templates

Templates wrap your prompt with specialized system instructions. The agent sees the template + your prompt, not your conversation.

// launch-super-coder
{ "prompt": "Fix the null check in auth.ts line 45...", "context_files": [{ "path": "/path/to/plan.md" }] }

Each launch tool selects the corresponding agent template automatically.

Models

Reasoning effort is derived automatically from the model name — no need to specify it separately.

Note: launch-super-planner always uses claude-opus-4.6 regardless of the model parameter.

Provider Chain

Tasks are routed through a configurable provider chain. The default order: Codex → Copilot → Claude CLI (fallback-only).

PROVIDER_CHAIN=codex,copilot,!claude-cli   (default)

• Prefix ! marks a provider as fallback-only (skipped during primary selection, used only when earlier providers fail).

• When a provider fails (rate limit, API error), the task automatically falls back to the next available provider in the chain.

• Model-provider compatibility is enforced: Claude models only route to claude-cli and copilot, not codex. If no compatible provider is available, the spawn fails with a clear error.

Multi-Account Rotation

Configure multiple GitHub PAT tokens for automatic rate-limit recovery. When one account hits 429 or 5xx, the server rotates to the next token mid-session without losing progress.

Configuration

# Comma-separated (recommended)
GITHUB_PAT_TOKENS=ghp_token1,ghp_token2,ghp_token3

# Or numbered
GITHUB_PAT_TOKEN_1=ghp_token1
GITHUB_PAT_TOKEN_2=ghp_token2

# Fallbacks (checked in order if above are empty)
GH_PAT_TOKEN=ghp_token
GITHUB_TOKEN=ghp_token
GH_TOKEN=ghp_token

How it works

1. Mid-session rotation: When the SDK detects a rate limit during execution, it rotates to the next available token and resumes the session with full context.

2. Post-session retry: If the session fails after completion, the spawner tries another token and retries.

3. All exhausted: If all tokens are in cooldown, tasks enter exponential backoff via the retry queue.

Task Dependencies

Tasks can wait for other tasks using the depends_on field. The dependent task stays in waiting status until all dependencies complete, then auto-starts.

{
  "prompt": "Deploy the service",
  "depends_on": ["build-task-id", "test-task-id"]
}

Dependencies are validated at spawn time:

• Circular dependencies are detected via DFS traversal. The error message includes the full cycle path (e.g., a -> b -> c -> a).

• Self-dependencies (a task depending on itself) are rejected.

• Duplicate dependency IDs are rejected.

• Missing dependencies (referencing a non-existent task ID) are rejected with a hint to check task:///all.

• Runtime deadlock detection — if a waiting task's dependencies form a cycle due to later state changes, the task is failed automatically with the cycle path.

Example: Chained pipeline

launch-super-planner(prompt: "...") → plan-tiger-42    [running]
launch-super-coder(prompt: "...", depends_on: ["plan-tiger-42"])   → code-falcon-17   [waiting]
launch-super-tester(prompt: "...", depends_on: ["code-falcon-17"]) → test-panda-88    [waiting]

plan-tiger-42 completes → code-falcon-17 auto-starts
code-falcon-17 completes → test-panda-88 auto-starts

Question Handling

When an agent calls ask_user, the task pauses and surfaces the question through MCP notifications and resources. Pending questions appear in task:///all and on the individual task resource.

Answering

// By choice number (1-indexed)
{ "task_id": "brave-tiger-42", "answer": "2" }

// By exact choice text
{ "task_id": "brave-tiger-42", "answer": "Use the existing database" }

// Custom freeform answer
{ "task_id": "brave-tiger-42", "answer": "CUSTOM: Use TypeScript instead" }

Questions time out after 30 minutes. The agent resumes automatically once you submit an answer.

Proactive Notifications

MCP servers can send notifications when tasks complete or need attention, but Claude Code's current MCP implementation doesn't fully support the standard notification paths (anthropics/claude-code#31893). Super Subagents works around this with two complementary mechanisms that work together — no polling required.

How you get notified

1. Live status in tool descriptions (automatic)

When a task completes or asks a question, the server triggers a tool list refresh. The message-agent and answer-agent tool descriptions include a live status footer showing what just happened:

message-agent description footer:
---
AGENT STATUS: 2 running | 1 needs answer | 1 just completed
- abc123 [completed] coder (2min ago)  output: .super-agents/abc123.output
- def456 [input_required] — waiting for answer
Read task:///all for full details.

answer-agent description footer:
---
ACTION REQUIRED — 1 task waiting for your answer:
- def456: "Which database?" Options: 1) PostgreSQL 2) MongoDB
Use answer-agent { "task_id": "def456", "answer": "1" }

This works out of the box — no configuration needed. Claude Code re-fetches tool descriptions automatically when the server signals tools/list_changed.

2. Hooks bridge (opt-in, recommended)

For mid-turn notifications (delivered after every tool call rather than waiting for the next turn), add a PostToolUse hook. The server writes task events to {cwd}/.super-agents/hook-state.json, and a bundled script reads unseen events and injects them as context.

One-line setup:

# From the repo / after npm install:
pnpm install-hooks        # or: bash scripts/install-hooks.sh

# After global npm install:
npx super-agents-install-hooks

# Check status without modifying anything:
bash scripts/install-hooks.sh --check

# Remove:
bash scripts/install-hooks.sh --uninstall

The installer checks your Claude Code environment, safely merges the hook into ~/.claude/settings.json (preserving existing hooks), creates a backup, and reports status. Requires jq.

Add to your Claude Code settings (~/.claude/settings.json or project .claude/settings.json):

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": ".*",
        "command": "/path/to/node_modules/mcp-supersubagents/scripts/super-agents-hook.sh"
      }
    ]
  }
}

Requirements: jq (preferred) or python3 (fallback). The script runs in ~10ms and exits 0 on all error paths — it won't slow down or break your workflow.

When a task completes or asks a question, you'll see context injected after the next tool call:

[SUPER-AGENT COMPLETED] Task abc123 has completed. Output: .super-agents/abc123.output
[SUPER-AGENT QUESTION] Task def456 is asking: "Which database?" Options: 1. PostgreSQL, 2. MongoDB. Use answer-agent to respond.

Why two approaches?

Both approaches are complementary. The tool description hack ensures Claude always sees current status when it considers which tools to call. The hooks bridge provides faster notification within a turn.

Environment Variables

No API keys? If neither PAT tokens nor OPENAI_API_KEY are configured, tasks automatically use the Claude Agent SDK as a fallback (requires claude CLI installed). Set DISABLE_CLAUDE_CODE_FALLBACK=true to prevent this.

Recommended Workflows

Parallel Feature Development

1. launch-super-coder({
     prompt: "Implement the /api/users endpoint. Read the OpenAPI spec at /docs/api.yaml for the schema...",
     context_files: [{ path: "/path/to/spec.md" }],
     labels: ["backend", "users-feature"]
   })
   → Task: brave-tiger-42

2. launch-super-tester({
     prompt: "Write E2E tests for the /api/users endpoint using the test patterns in /tests/...",
     context_files: [{ path: "/path/to/test-patterns.md" }],
     depends_on: ["brave-tiger-42"],
     labels: ["testing", "users-feature"]
   })
   → Task: calm-falcon-17 (waiting for brave-tiger-42)

3. launch-super-researcher({
     prompt: "Research best practices for user data pagination. Compare cursor vs offset...",
     labels: ["research", "users-feature"]
   })
   → Task: swift-panda-88 (starts immediately, runs in parallel with brave-tiger-42)

4. Continue your own work. MCP notifications arrive as tasks complete.

5. brave-tiger-42 completes → calm-falcon-17 auto-starts (dependencies satisfied)

6. Review results:
   - Read resource: task:///all
   - tail -20 .super-agents/brave-tiger-42.output
   - message-agent({ task_id: "brave-tiger-42", message: "Add input validation" })

Plan-Code-Test Pipeline

1. launch-super-planner(...)  → Creates architecture plan with builder-briefing.md
2. launch-super-coder(...)    → depends_on planner, uses briefing as context_file
3. launch-super-tester(...)   → depends_on coder, uses tester-checklist.md as context_file

Each stage auto-starts when its dependencies complete. The planner always uses claude-opus-4.6 for maximum reasoning quality.

Task Lifecycle

pending → running → completed
                  → failed
                  → cancelled
                  → timed_out
                  → rate_limited → (auto-retry) → pending → running → ...

pending → waiting (dependencies) → pending → running → ...
pending / waiting → timed_out    (if timeout expires before execution starts)
pending / waiting → cancelled
pending / waiting → failed       (e.g. missing or circular dependencies)

Eight internal states map to five MCP states (working, input_required, completed, failed, cancelled) for clients that use MCP task primitives.

Limits

• Max in-memory tasks: 100 (oldest terminal tasks evicted; if all 100 are active, spawn returns an actionable error)

• Max output lines per task: 2,000 (older lines trimmed in-place)

Persistence

Tasks persist to ~/.super-agents/{md5(cwd)}.json. Survives server restarts. Rate-limited tasks auto-retry on reconnect. Output files persist in {cwd}/.super-agents/ for post-hoc review.

Development

# Clone
git clone https://github.com/yigitkonur/mcp-supersubagents.git
cd mcp-supersubagents

# Install dependencies
pnpm install
# Build (TypeScript + copy MDX templates)
pnpm build

# Watch mode (auto-reload)
pnpm dev

# Run the compiled server
pnpm start

Build note: tsc only compiles .ts files. The build script automatically copies .mdx template files to build/templates/. If you modify templates, rebuild to pick up changes.

Companion Tools

Super Subagents agent templates reference companion MCP servers and skills that dramatically improve agent output quality. The MCP servers provide tools the agents call during execution; the skills inject domain-specific patterns and methodology into agent prompts.

One-line ecosystem install

# Install all companion MCP servers + skills + hooks in one shot:
npx super-agents-install-ecosystem

# Or from the repo:
pnpm install-ecosystem

This installs all 5 companion MCP servers into your Claude Code config, all 3 required skills, and the PostToolUse notification hook. Run with --check to see current status without modifying anything, or --uninstall to remove everything.

MCP Servers

These MCP servers are used by the agent templates. Install them individually or use the ecosystem installer above.

# crash-think-tool — structured reasoning (no API key needed)
claude mcp add crash-think-tool -- npx -y crash-mcp@latest

# morph — code editing + warpgrep (requires Morph API key from https://morphllm.com)
claude mcp add morph \
  -e MORPH_API_KEY=your-morph-api-key \
  -e ENABLED_TOOLS=warpgrep_codebase_search,warpgrep_github_search \
  -- npx -y @morphllm/morphmcp@latest

# skills-as-context — skill discovery (no API key needed)
claude mcp add skills-as-context -- npx -y mcp-skills-as-context@latest

# research-powerpack — web + Reddit research (requires API keys)
claude mcp add research-powerpack \
  -e SERPER_API_KEY=your-serper-key \
  -e OPENROUTER_API_KEY=your-openrouter-key \
  -- npx -y mcp-researchpowerpack@latest

# ask-questions — interactive user questions
claude mcp add ask-questions -- npx -y mcp-vibepowerpack@latest

See each package's README for full configuration options and optional API keys.

Skills

Agent templates auto-load skills from skills.sh to inject domain expertise. Three skills are directly referenced by name:

Additionally, the coder template dynamically discovers skills at runtime via search-skills based on the detected tech stack (e.g., "nextjs app router patterns", "rust async tokio patterns"). The full skill catalog is at yigitkonur/skills-by-yigitkonur (14 skills available).

# Install all three required skills:
npx skills add yigitkonur/skills-by-yigitkonur/skills/planning
npx skills add yigitkonur/skills-by-yigitkonur/skills/playwright-cli
npx skills add yigitkonur/skills-by-yigitkonur/skills/research-powerpack

# Optional — install ALL available skills from the catalog:
npx skills add yigitkonur/skills-by-yigitkonur/skills/copilot-review-init
npx skills add yigitkonur/skills-by-yigitkonur/skills/design-soul-saas
npx skills add yigitkonur/skills-by-yigitkonur/skills/devin-review-init
npx skills add yigitkonur/skills-by-yigitkonur/skills/greptile-config
npx skills add yigitkonur/skills-by-yigitkonur/skills/mcp-apps-builder
npx skills add yigitkonur/skills-by-yigitkonur/skills/mcp-cli
npx skills add yigitkonur/skills-by-yigitkonur/skills/mcp-server-tester
npx skills add yigitkonur/skills-by-yigitkonur/skills/mcp-use-code-review
npx skills add yigitkonur/skills-by-yigitkonur/skills/snapshot-to-nextjs
npx skills add yigitkonur/skills-by-yigitkonur/skills/supastarter
npx skills add yigitkonur/skills-by-yigitkonur/skills/tauri-devtools

Troubleshooting

• Configure multiple PAT tokens via GITHUB_PAT_TOKENS for automatic rotation.

• With a single token, tasks enter exponential backoff (5m to 2h, max 6 retries).

• Check account status: read the system:///status MCP resource.

• Failed tokens enter a 60-second cooldown before reuse.

• Tokens are loaded in priority order: GITHUB_PAT_TOKENS > GITHUB_PAT_TOKEN_1..N > GH_PAT_TOKEN > GITHUB_TOKEN / GH_TOKEN.

• Verify tokens have Copilot access. A PAT without Copilot permissions will fail silently.

• Check the server stderr output for [account-manager] Initialized with N account(s).

• Up to 100 tokens are supported.

• Tasks persist to ~/.super-agents/{md5(cwd)}.json and survive server restarts.

• Rate-limited tasks auto-retry when the server reconnects.

• Live output files at {cwd}/.super-agents/{task-id}.output persist for post-hoc review.

• Use cancel-agent with task_id: "all", clear: true, confirm: true to clear all tasks and delete the persistence file.

• Use the specialized launch tools (launch-super-coder, launch-super-planner, launch-super-tester, launch-super-researcher). Each enforces structured briefs and produces dramatically better results.

• Agents run with NO shared memory -- your prompt is their ONLY context. Include all necessary file paths, background, and success criteria.

• Attach context files (.md) with detailed plans or specifications.

• For launch-super-coder, provide a minimum of 1,000 characters with objective, files, success criteria, constraints, and patterns.

• The server performs a graceful shutdown on SIGINT/SIGTERM: it aborts all fallback sessions, cleans up SDK bindings, kills tracked processes, and closes output file handles.

• If the MCP transport breaks (broken pipe), the server waits up to 15 seconds (configurable via BROKEN_PIPE_FORCE_EXIT_TIMEOUT_MS) for cleanup before force-exiting.

• On process.exit, all tracked child processes are force-killed synchronously to prevent orphaned sessions.