agent-code-squad 0.1.13

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

MCP client config (example)

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

Project config (recommended)

Create <repo_root>/.codex/code-squad/config.json to set defaults per project.

Priority: .codex/code-squad/config.json → CLI flags → built-in defaults.

Example:

{
  "dispatch_dir": "~/.codex/code-squad",
  "defaults": {
    "model": "gpt-5.2-codex",
    "sandbox": "workspace-write",
    "approval_policy": "never",
    "auto_context_pack": {
      "enabled": true,
      "glob": "**/*",
      "max_files": 14,
      "max_snippets": 28,
      "max_total_chars": 24000,
      "hints": []
    },
    "worker_concurrency": 2
  },
  "guardrails": {
    "enforce_sparse_checkout": true,
    "early_scope_enforcement": true,
    "strict_context_pack_scope": true,
    "require_patch": true
  },
  "energy_saver": {
    "default_reasoning_effort": "medium",
    "max_reasoning_effort": "medium"
  }
}

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.

Default preflight (code_squad_execute)

• Phase A runs automatically before execution (set options.preflight=false to skip):
  • Scope preview: validates allow_globs/deny_globs and samples files (uses rg; missing rg triggers a confirmation question).
  • Context budget check: flags very high auto_context_pack.max_total_chars, overly broad hints, or disabled context packs.
  • Prompt rules: ensures prompts include patch-only, acceptance/verification, and “ask if missing info” instructions.
• Decision logic:
  • High-confidence pass → auto enqueue/run (preflight summary is included in the response and run artifacts).
  • Gaps (wide/empty scope, oversized context, missing prompt rules) → return preflight.needs_user_confirm=true, next_action=confirm, no tasks started.
• Artifacts: preflight summary is stored under runs/<run_id>/artifacts/docs/preflight.md and embedded in artifacts.preflight_doc + the preflight block in responses/index JSON.

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
  }
}

Multi-Agent Pipeline (roles + depends_on)

• Optional per-task role (planner/coder/reviewer/integrator) and depends_on lists enable staged pipelines.
• Tasks enqueue only after all dependencies finish with state=completed; failed/cancelled/timeout deps mark dependents as blocked (terminal).
• code_squad_status / code_squad_tick / background finalizer auto-check dependencies and enqueue ready tasks—no manual requeue needed.
• Use code_squad_apply_many to integrate multiple patches in order (default dry-run, stop on first error). Flags: options.dry_run (default true), options.stop_on_error (default true), options.three_way (default true), options.stage_index (default true).

Example:

{
  "tasks": [
    {
      "name": "plan",
      "role": "planner",
      "prompt": "Decompose feature X into sub-tasks for api/ui/docs.",
      "allow_globs": ["docs/**"]
    },
    {
      "name": "api fix",
      "role": "coder",
      "depends_on": ["plan"],
      "prompt": "Apply planner decisions to API layer",
      "allow_globs": ["apps/api-fastapi/**"],
      "deny_globs": ["**/node_modules/**", "**/.codex/**"]
    },
    {
      "name": "ui polish",
      "role": "coder",
      "depends_on": ["plan"],
      "prompt": "Apply planner decisions to UI layer",
      "allow_globs": ["apps/ui/**"],
      "deny_globs": ["**/node_modules/**", "**/.codex/**"]
    },
    {
      "name": "review",
      "role": "reviewer",
      "depends_on": ["api fix", "ui polish"],
      "prompt": "Review diffs from api/ui tasks and propose risk notes",
      "allow_globs": ["apps/api-fastapi/**", "apps/ui/**", "docs/**"]
    }
  ]
}

After collect, run a batch integration dry-run:

code_squad_apply_many(
  cwd="/path/to/repo",
  run_id="<run>",
  slugs=["api-fix", "ui-polish"],
  options={"dry_run": true, "stop_on_error": true}
)

Auto Context Packs (Default)

If a task does not provide context_pack, automatic context packing runs by default (cached under <dispatch_base>/context_packs/).

• To disable: options.auto_context_pack=false (or config "defaults.auto_context_pack.enabled": false).
• 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.
• The pack seeds common entrypoints (AGENTS.md, README*, common dependency/build files) before doing rg snippet extraction.

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.

Scope Guardrails (Hardening)

• enforce_sparse_checkout (default true): if allow_globs is set, sparse-checkout runs before the subagent starts; failures hard-fail the task.
• early_scope_enforcement (default true): once a patch appears in stdout, scope is checked immediately; violations cancel the job early.
• strict_context_pack_scope (default true): provided task.context_pack is rejected if it contains out-of-scope paths (based on allow_globs/deny_globs).
• require_patch (default true): tasks that finish without a patch are treated as failed (scope limits.require_patch).

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 (last human line, trimmed) plus has_patch.
• code_squad_events defaults to max_items=30 and filters out thread/turn/heartbeat noise; it only returns human/diff-bearing events unless include_noise=true (or options.debug=true).
• code_squad_collect persists patches to disk and returns paths by default; set options.include_patch=true to inline patch text in the response.

Reasoning effort cap (eco)

This server enforces model_reasoning_effort<=max_reasoning_effort for all tasks (default max is medium).

• If you want lower effort, set options.model_reasoning_effort="low" (or options.reasoning_effort="low").
• Requests above the configured max are clamped down to the max.

Tools

• code_squad_capabilities_get: defaults and dispatch paths.
• code_squad_capabilities_get supports cwd to resolve per-repo defaults from <repo_root>/.codex/code-squad/config.json (useful when the MCP server is started globally without a fixed cwd).
• code_squad_scope_preview: preview allow/deny globs before running tasks.
• 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_apply: apply a collected patch to the repo worktree (default dry-run; supports --3way + --index).
• code_squad_apply_many: apply multiple collected patches in order (default dry-run, stop on first error).
• 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 .codex/code-squad/config.json or CLI flags (config takes priority over CLI).