CrossSubAgent MCP

Cross-Vendor AI SubAgent Orchestration for AI Coding Assistants.

Call, orchestrate, monitor, and collaborate with SubAgents from other AI providers (e.g. Google Antigravity / AGY invoking Claude Code CLI with a custom DeepSeek v4 Flash endpoint, Aider, direct LLM APIs). Supports async batch execution, Git worktree isolation, multi-agent meetings, automated code review suites, shared blackboard memory, typed artifacts, peer-review loops, and FinOps governance.

🚨 Delegation Golden Rule: subagent_run vs subagent_spawn

[!IMPORTANT]

• Single Subagent Execution: Use subagent_run. It is the most suitable choice (synchronous execution returning output directly upon completion without requiring polling loops or timers).
• Multiple / Concurrent Subagents: subagent_spawn (or subagent_batch_spawn / subagent_pipeline_spawn) is MANDATORY. Always dispatch multiple subagents asynchronously in parallel with dedicated Git Worktrees (subagent_workspace_branch).

⚡ Automated 1-Click Installation (Zero-Clone or Custom Directory)

Install CrossSubAgent MCP and its SKILL.md / Rules into your AI coding assistant in a single command:

Option 1: NPX Mode (Default)

# Interactive setup
npx -y cross-subagent install

# Install in all detected tools (Claude Code, Antigravity, OpenCode)
npx -y cross-subagent install --all

# Or target specific tools
npx -y cross-subagent install --antigravity
npx -y cross-subagent install --claude
npx -y cross-subagent install --opencode

Option 2: Clean Custom Directory Installation

You can install CrossSubAgent from any custom directory on your machine:

# Via CLI command
node bin/cross-subagent.js install --all --dir /path/to/my/CrossSubAgent

# Via included installer script
./install.sh --dir /path/to/my/CrossSubAgent

# Or local build mode
./install.sh --local

Check Installation Status or Uninstall

# Check status across all tools
npx -y cross-subagent status

# Uninstall cleanly
npx -y cross-subagent uninstall --all

🚀 Workspace & Global Initialization (cross-subagent init)

Before running subagents, initialize the .subagents/ configuration structure:

1. Initialize for Current Project (Workspace Level)

Creates .subagents/, config.yaml, .env.example, .gitignore, and 10 ready-to-use subagent templates in your current project repository:

npx -y cross-subagent init

2. Initialize Globally (User Level — All Projects)

Creates ~/.subagents/ in your user home folder. Any project on your system will automatically inherit these subagents, API keys, and settings:

npx -y cross-subagent init --global

3. Verify & Diagnose Your Setup

# List all discovered subagents and check their readiness status
npx -y cross-subagent list

# Run full health diagnostics (Node.js, CLIs, YAML configs)
npx -y cross-subagent doctor

🎯 Supported Environments & What Is Configured

| Tool | MCP Configuration | SKILL.md / Rules Configured | | :--- | :--- | :--- | | Google Antigravity (IDE & CLI) | ~/.gemini/config/mcp_config.json + permissions in settings.json | ~/.gemini/config/skills/cross-subagent/SKILL.md + ~/.gemini/config/rules/cross-subagent.md | | Claude Code | ~/.claude/.mcp.json & ~/.claude.json | ~/.claude/skills/cross-subagent/SKILL.md + ~/.claude/CLAUDE.md | | OpenCode | ~/.config/opencode/config.json | ~/.config/opencode/skills/cross-subagent/SKILL.md + ~/.config/opencode/rules/cross-subagent.md |

🛠️ Complete Tools Reference (27 Tools)

1. Lifecycle & Single-Session (8 Tools)

| Tool | Description | Key Parameters | |---|---|---| | subagent_list_available | Lists all subagents declared in .subagents/ with capabilities, provider, type, model, and readiness status. | working_dir, capability (optional), type (cli|api) | | subagent_run | Executes a subagent synchronously (one-shot) and returns full output and exit code. (Recommended for single-agent tasks). | agent_id (required), prompt (required), working_dir, timeout_seconds, display_terminal | | subagent_spawn | Starts an asynchronous subagent in the background and returns a session_id immediately. (Mandatory for multi-agents). | agent_id (required), initial_prompt, working_dir, display_terminal | | subagent_send_message | Sends a follow-up prompt or stdin input to an active subagent session (multi-turn). | session_id (required), message (required) | | subagent_get_status | Checks real-time execution state (running, waiting_input, completed, failed, killed, timeout), duration, PID, and tokens. | session_id (required) | | subagent_get_logs | Retrieves buffered stdout/stderr/thought/tool logs from a subagent session. | session_id (required), tail_lines, offset | | subagent_list_sessions | Lists all active and recent subagent sessions. | status_filter (active|all) | | subagent_kill | Gracefully (SIGTERM) or forcefully (SIGKILL) terminates an active subagent session. | session_id (required), force (boolean) |

2. Git Worktree Isolation & Lifecycle (3 Tools)

| Tool | Description | Key Parameters | |---|---|---| | subagent_workspace_branch | Creates an isolated Git branch and dedicated Git Worktree on disk so subagents work without file conflicts. | base_path, branch_name, base_ref, copy_untracked | | subagent_workspace_merge | Runs a validation command (tests, lint), squash/merge the isolated worktree branch back to target, and cleans up. | workspace_id (required), target_branch, strategy (squash|merge|rebase), commit_message, run_validation_cmd, cleanup_worktree | | subagent_close_worktree | Deletes and cleans up one or multiple isolated Git worktrees and removes ephemeral branches. | workspace_id, workspace_ids, all (boolean), delete_branch (boolean), force (boolean) |

3. Asynchronous Composite Orchestration (3 Tools)

| Tool | Description | Key Parameters | |---|---|---| | subagent_batch_spawn | Starts a parallel Map/Batch execution across a list of items with concurrency control. Returns batch_id immediately (non-blocking). | agent_id (required), items (required), prompt_template (required), max_concurrency, auto_isolate_worktrees | | subagent_pipeline_spawn | Starts a sequential pipeline chaining multiple agents with automatic context passing between stages. Returns pipeline_id immediately. | stages (required), pipeline_name, initial_context, working_dir, fail_fast | | subagent_orchestration_status | Retrieves progress %, stage results, and outputs of a running batch or pipeline — or cancels it. | orchestration_id (required), cancel (boolean) |

4. Multi-Agent Meetings & Code Review Suite (3 Tools)

| Tool | Description | Key Parameters | |---|---|---| | subagent_multi_agents_meeting | Orchestrates a technical debate between multiple subagents ($\ge 2$) with debate rounds, worktree isolation, and list-based structured output (ask, quick_answer, answer, how_to_make, number_of_agents, agents_idx). | questions (required, array), agent_ids (required, array), rounds, isolate_worktree, context, working_dir, synthesizer_agent_id | | subagent_code_review_analysis | Audits the codebase across 1 or multiple subagents partitioned by directory scope, producing and publishing a Code Review Audit artifact. | reviewer_agent_id, reviewers (array of scopes), scope_paths, criteria, isolate_worktrees, publish_artifact, working_dir | | subagent_apply_code_review_audit | Implements findings from a Code Review Audit across subagents in parallel with dedicated worktrees and automated test verification. | audit_artifact_id, findings, implementer_agent_ids, isolate_worktrees, auto_validate, validation_cmd, auto_merge, target_branch, working_dir |

5. Shared Memory & Blackboard (2 Tools)

| Tool | Description | Key Parameters | |---|---|---| | subagent_blackboard_set | Writes a key-value entry into the collective agent memory with namespaces, versioning, and optional TTL expiration. | key (required), value (required), namespace, ttl_seconds, author_session_id | | subagent_blackboard_get | Reads shared values or lists keys from the collective memory by key, namespace, or prefix. | key, namespace, prefix, include_expired |

6. Typed Artifacts & Deliverables Registry (2 Tools)

| Tool | Description | Key Parameters | |---|---|---| | subagent_artifact_publish | Publishes a versioned, SHA-256 hashed deliverable (diff, JSON, report, markdown, code, spec) to the multi-agent artifact store. | artifact_id (required), type (required), content (required), metadata, author_agent_id, overwrite | | subagent_artifact_fetch | Retrieves an artifact by ID and optional version, or lists all artifacts. Can write to disk. | artifact_id, version, destination_path |

7. Quality Control & Structured Validation (2 Tools)

| Tool | Description | Key Parameters | |---|---|---| | subagent_peer_review | Performs an automated cross-model code audit on workspace files, git diffs, or session output using an agentic AI with auto-fix loop. | reviewer_agent_id (required), files, git_diff_base, instructions, strict, source_session_id, diff_content, criteria, max_fix_rounds, auto_fix | | subagent_export_structured | Extracts and validates a typed JSON object from a subagent session output or raw text. | session_id, raw_text, expected_fields |

8. Governance, FinOps & Safety (4 Tools)

| Tool | Description | Key Parameters | |---|---|---| | subagent_get_metrics | Returns consolidated FinOps telemetry: tokens in/out, estimated USD cost by model, latency, and success rates. | agent_id, session_id | | subagent_set_budget | Sets a circuit-breaker policy (max cost, tokens, or duration) on sessions or batches with warn/kill on breach. | target_type, target_id, max_cost_usd, max_tokens, max_duration_seconds, on_breach | | subagent_watchdog_healthcheck | Proactively scans running agents to detect infinite tool-call loops, stalled sessions, and deadlock candidates. | — | | subagent_consensus_vote | Submits a technical decision to N models and computes consensus by weighted quorum. | question (required), options (required), voter_agent_ids (required), working_dir |

⚡ Real-Time Logging & Reasoning Stream

Subagent execution captures reasoning blocks, tool usages, and commands in real time:

• [THOUGHT] : Captures <thinking> / reasoning_content streams from Anthropic, DeepSeek, and Gemini models.
• [TOOL ] : Captures tool calls, bash commands, and MCP actions.
• [SYSTEM ] : Captures loop iterations, status changes, and circuit-breaker signals.
• [STDOUT ] / [STDERR ] : Standard output streams.

Logs are continuously persisted in .subagents/logs/<session-id>.log and accessible via subagent_get_logs.

💡 Usage Examples

1. Multi-Agent Technical Meeting (subagent_multi_agents_meeting)

{
  "questions": [
    "Quelles sont des tools MCP pertinents à ajouter à notre projet ?",
    "Comment structurer le moteur de review de code ?"
  ],
  "agent_ids": ["agy-coder", "claude-deepseek", "agy-coder"],
  "rounds": 2,
  "isolate_worktree": true
}

2. Code Review Analysis & Auto-Fix Implementation

// Step 1: Run comprehensive codebase audit
const audit = subagent_code_review_analysis({
  "reviewers": [
    { "agent_id": "agy-coder", "scope_path": "src/core/" },
    { "agent_id": "claude-deepseek", "scope_path": "src/tools/" }
  ],
  "isolate_worktrees": true
});

// Step 2: Apply audit recommendations across subagents with tests
subagent_apply_code_review_audit({
  "audit_artifact_id": audit.artifactId,
  "implementer_agent_ids": ["claude-deepseek", "agy-coder"],
  "isolate_worktrees": true,
  "auto_validate": true,
  "validation_cmd": "npm test"
});

3. Worktree Cleanup (subagent_close_worktree)

{
  "workspace_ids": ["ws_1787036_abc123", "ws_1787036_def456"],
  "delete_branch": true
}

⚙️ Configuration & Environment (.subagents/)

.subagents/
├── config.yaml                   # Global options (displayTerminal, defaults)
├── .env                          # API keys & model overrides
└── agents/                       # Declarative YAML subagents
    ├── claude-deepseek.yaml      # Claude Code CLI on DeepSeek v4 Flash backend
    ├── claude-kimi.yaml          # Claude Code CLI on Kimi / Moonshot AI (1M context)
    ├── claude-openrouter.yaml    # Claude Code CLI on OpenRouter Anthropic endpoint
    ├── claude-anthropic.yaml     # Claude Code CLI official Anthropic
    ├── agy-coder.yaml            # Antigravity AGY CLI agent
    ├── aider-architect.yaml      # Aider CLI agent
    ├── deepseek-direct.yaml      # Direct DeepSeek API (no CLI needed)
    ├── openrouter-direct.yaml    # Direct OpenRouter API (200+ models, no CLI needed)
    ├── kimi-direct.yaml          # Direct Kimi / Moonshot AI API (no CLI needed)
    └── ollama-local.yaml         # Local offline LLM (Ollama)

📄 License

MIT © 2026 CrossSubAgent Team