agent-code-squad 0.1.5

MCP server for orchestrating multi-subagent code runs with minimized context and patch-only outputs.

agent-code-squad

Python MCP server that queues code-writing subagents with minimal context packs, isolated git worktrees, and patch-first collection. Heavy work (git worktree add + codex exec start) runs in a background worker to avoid tool-call timeouts.

Quickstart

cd mcp-tools/agent-code-squad
poetry env use python3
poetry install
poetry run agent-code-squad --transport stdio

MCP client config (example)

[mcp_servers.agent-code-squad]
command = "poetry"
args = ["run", "agent-code-squad", "--transport", "stdio"]
cwd = "/Volumes/workspace/dzrlab/k3s-test/mcp-tools/agent-code-squad"

Recommended flow

1. code_squad_execute: start tasks immediately and return quickly (default non-blocking).
2. Optional manual flow:
   • code_squad_run: queue tasks and enqueue workers right away.
   • code_squad_tick: optional bounded status refresh (enqueues already-queued tasks if needed).
   • code_squad_status / code_squad_events: poll light status or stream JSONL events.
   • code_squad_collect: extract patches from job stdout and persist under run artifacts (works even after worktree cleanup).
   • code_squad_verify: optional; runs compileall/pytest or custom options.commands arrays; results saved under artifacts.
   • code_squad_report: emit run/task summary as report.json and report.md.
   • code_squad_prune: clean up old runs/worktrees by retention policy.
   • code_squad_cancel (optional): cancel a job or all tasks in a run.
   • code_squad_cleanup: drop worktrees and optionally delete run artifacts.

Modify Multiple Modules

When the user request is “modify several modules”, prefer one task per module and enforce boundaries so parallel work stays precise.

• Put each module under a distinct directory (example: modules/<name>/).
• Use allow_globs per task to restrict which files a task is allowed to touch.
• Use deny_globs to protect shared areas (configs, app entrypoints, shared libs) from module tasks.
• allow_globs / deny_globs are also injected into the subagent prompt as hard rules to reduce scope drift.
• If allow_globs is set, the worktree attempts a best-effort git sparse-checkout to physically hide non-allowed paths (further reducing context + accidental edits). The mapping prefers the tightest directory prefix (e.g. modules/user/** → modules/user).
• If scope is violated, collection marks scope.ok=false and writes a scope artifact under runs/<run_id>/artifacts/scope/<slug>.json.

Example code_squad_execute input:

{
  "cwd": "/path/to/repo",
  "tasks": [
    {
      "name": "user module",
      "scope_name": "modules/user",
      "allow_globs": ["modules/user/**"],
      "deny_globs": ["shared/**", "config/**", "app/**"],
      "prompt": "Fix bug in user module: ... (patch only)"
    },
    {
      "name": "billing module",
      "scope_name": "modules/billing",
      "allow_globs": ["modules/billing/**"],
      "deny_globs": ["shared/**", "config/**", "app/**"],
      "prompt": "Fix bug in billing module: ... (patch only)"
    }
  ],
  "options": {
    "poll_interval": 1.0,
    "wait_seconds": 0,
    "cleanup": true,
    "keep_failed": true
  }
}

Auto Context Packs (Optional)

If a task does not provide context_pack, you can enable automatic context packing:

• options.auto_context_pack: dict with keys glob, max_files, max_snippets, max_total_chars, and optional hints.
• Query selection per task: task.context_query → task.scope_name → task.name.
• If a task specifies allow_globs / deny_globs, the context pack generation applies the same filters to reduce cross-scope leakage.
• Context packs are cached under <dispatch_base>/context_packs/ to avoid repeated rg scans.

Change Size Limits (Optional)

To prevent large/low-signal edits:

• Per-task: task.max_touched_files, task.max_patch_bytes
• Or defaults: options.max_touched_files, options.max_patch_bytes

If limits are exceeded, scope is marked ok=false and code_squad_execute fails the task.

Cleanup and Retention

Worktree cleanup is controlled by options.cleanup / options.keep_failed (used by the background finalizer).

• options.cleanup (default true): remove worktrees after execution
• options.keep_failed (default true): keep failed and timeout task worktrees for debugging
• options.cleanup_delete_run_artifacts (default false): also delete run artifacts (use with care)

For periodic cleanup of old runs/worktrees, use code_squad_prune:

• Defaults: keep last 5 runs, keep successful runs for 3 days, keep failed/timeout runs for 1 day
• dry_run=true by default; set dry_run=false to actually delete

Logs and Artifacts

Each run writes an index file to make review/debug easier:

• runs/<run_id>/artifacts/index.json: run/task summary plus expected artifact paths
• code_squad_execute returns quickly with index_path and next_poll_ms; heavy work is done asynchronously.
• runs/<run_id>/artifacts/timeline.jsonl: structured timeline events (used by recent_events in status/execute/collect).
• code_squad_status returns progress, next_action, next_poll_ms, and a per-task message.
• code_squad_events(include_noise=false) filters out thread/turn/heartbeat noise and command/tool-call items by default

Reasoning effort cap (eco)

This server enforces model_reasoning_effort<=medium for all tasks.

• If you want lower effort, set options.model_reasoning_effort="low" (or options.reasoning_effort="low").
• Requests for high are clamped down to medium.

Tools

• code_squad_capabilities_get: defaults and dispatch paths.
• code_squad_context_pack: ripgrep-based context pack with snippet/char caps.
• code_squad_run: queue tasks with per-task model/sandbox/approval/extra_config (auto-enqueues workers).
• code_squad_execute: start run and return quickly (optional short wait via options.wait_seconds).
• code_squad_tick: optional bounded worker pump (refresh a few running).
• code_squad_status: summarize task states with compact last messages.
• code_squad_events: stream compacted JSONL events per job using cursors (supports noise filtering).
• code_squad_collect: extract patch + touched files from job stdout and persist under artifacts.
• code_squad_verify: run compileall/pytest or custom commands using sys.executable, persisting results.
• code_squad_report: write report.json/report.md under run artifacts.
• code_squad_prune: clean up old runs/worktrees by retention policy.
• code_squad_cancel: cancel a job or whole run (sets state to cancelled).
• code_squad_cleanup: remove worktrees and (optional) run artifacts under .codex/code-squad/.

Debug output

All tools accept options.debug=true to return a debug block (paths, timings, raw stdout/stderr/events). Default responses stay minimal and omit worktree/run/dispatch paths, trace IDs, PIDs, and full prompts.

For robustness, options is treated as best-effort: non-dict inputs are coerced to {} rather than hard-failing validation.

Paths and defaults

• Run metadata: <dispatch_base>/runs/<run_id>/run.json.
• Job artifacts: <dispatch_base>/runs/<run_id>/jobs/<job_id>/{meta.json,stdout.jsonl,stderr.log,last_message.txt}.
• Worktrees: <repo>/.codex/code-squad/worktrees/<run_id>/<task_slug>.
• Dispatch base (default): <repo>/.codex/code-squad.
• Defaults: model gpt-5.1-codex-max, sandbox workspace-write, approval policy never, worker concurrency 2.
• Override via CLI flags or AGENT_CODE_SQUAD_* env vars:
  • AGENT_CODE_SQUAD_MODEL
  • AGENT_CODE_SQUAD_SANDBOX
  • AGENT_CODE_SQUAD_APPROVAL_POLICY
  • AGENT_CODE_SQUAD_WORKER_CONCURRENCY