subtask MCP server

subtask

A local delegation scheduler for coding agents. One MCP server (and a twin CLI) lets Claude Code, Codex, Kimi Code or OpenCode start work in parallel, wait for it with a single call, and read back a short summary with evidence. It picks an engine that can take the job, books money and slots safely across processes, and says honestly how isolated each run is.

start_many([{task: "Fix the flaky test in tests/test_sync.py", repo: "/src/app", verify: "pytest -q tests/test_sync.py"},
            {task: "List every caller of parse_date()", kind: "read", readonly: true, cwd: "/src/app"}])
  -> st-4f2a91 started · sonnet-api · branch subtask/st-4f2a91 · sandbox
     st-77c0de started · haiku-api · /src/app · readonly
wait(["st-4f2a91", "st-77c0de"])          # Claude Code shows: Subtask · 01:16 · 1/2 ended — st-4f2a91 running tests: pytest -q
  -> st-4f2a91 done · sonnet-api · 6m · 0.412$ · verified · ...
     ## Summary (≤10 lines: the answer, files, commits, tests, what is left)
result("st-4f2a91", evidence=True)        # JSON: base/head, changed files, observed commands, verify exit code, cost

Why

• Save the caller's context. The worker's search, test runs and dead ends stay in its own session; the caller reads about ten lines.
• Few round trips. start_many + one wait replace a polling loop.
• Use whatever has room. engine="auto" filters engines that can enforce the requested isolation, are installed, fit the budget and have quota, then ranks them with an explicit utility (subtask routing explain).
• Money is a primitive. Paid engines reserve their budget before any work, under one lock with the slot; every reservation is closed exactly once.
• Evidence, not claims. verify="..." runs your check on the commit the worker left; result(evidence=True) separates what subtask observed from what the worker reported.

Install

The distribution is subtask-mcp (the PyPI name subtask is an unrelated project). Full guide, per client, with native commands: docs/install.md.

uv tool install "git+https://github.com/tedin7/subtask@main"   # or: uv tool install /path/to/checkout
subtask install --client all          # prints the plan for every detected client
subtask install --client all --yes    # applies it: MCP server + skill
subtask doctor --client all           # checks app, config entry and a real handshake

subtask --version reports the installed Git commit when the installer records it. For local, editable, or registry installations without Git provenance it reports commit unknown.

Jev provides advisory workflow checks automatically, or only when requested:

subtask jev                 # policy, key availability and the current process's budget limits
subtask jev setup           # guided setup; key input is hidden
subtask jev auto            # automatic routing, feedback and final delivery advice
subtask jev manual          # explicit review submissions only
subtask jev off             # block new Jev submissions

New installations start in manual mode. The policy and private key are shared by the configured clients. Enter keys through hidden subtask jev setup input or explicit stdin, never chat, argv or tool arguments. In auto, start_many appends routing advice, reply includes feedback advice, and final wait / result include evidence consistency and risk triage. Read this advice together with the existing baseline output. Routing and feedback preserve authorized work and worker instructions. manual requires explicit submissions; off blocks new ones.

These extra checks share the existing cap and deduplicate identical content. skipped, blocked and unknown are not passes; never retry an unknown send. Distinguish raw provider_choice from filtered assessment: a failed verification can veto supported deterministically, without being a Jev finding. Suggested next actions grant no authority, replace no checks, and trigger no automatic model fallback, merge, retry or release. See Jev setup and limits and the workflow study and its limits. These instructions describe the upcoming release; they do not certify a live install.

Claude Code plugin: claude plugin marketplace add tedin7/subtask then claude plugin install subtask@subtask. Codex: codex plugin marketplace add tedin7/subtask. API engines read ANTHROPIC_API_KEY from ~/.config/subtask/env (chmod 600).

Engines

engine	pays with	read-only	isolation it can enforce
haiku-api, sonnet-api, opus-api	API key, monthly cap	yes	sandbox (Claude Code OS sandbox)
codex	Codex login (quota from local session files)	yes	sandbox (workspace-write), isolated
opencode-go	opencode-go subscription	no	worktree, isolated
kimi	Kimi login	no	worktree, isolated
dsh	DeepSeek key, same cap (subtask-mcp[dsh])	no	worktree
opencode	OpenCode default provider (manual only)	no	worktree, isolated

Add an engine without touching the core: an EngineAdapter registered under the subtask.engines entry point (see CONTRIBUTING.md).

Isolation, honestly

• worktree (default): a git worktree and branch per writing job. It prevents collisions; it is not a host sandbox.
• sandbox: the engine's own sandbox. Same user: a guard rail.
• isolated: bubblewrap. Read-only system, writable worktree and git dir only, a private HOME with only the engine's own state. Needs bwrap.
• untrusted: sandbox or stronger, and no network for the worker's commands.

A job that cannot get the policy it asked for is refused, never downgraded. Output is redacted for common secret formats before it is saved or shown; redaction is a second layer, not a guarantee. See SECURITY.md.

Tools (MCP) and CLI

tool	what it does
start(task, kind, repo, cwd, files, readonly, engine, max_usd, effort, base, max_turns, policy, verify, isolation, max_retries, adversarial, context_refs, auto_repomap, tier, invariants, allowed_paths, symbol_scope, oracle_cmd)	start one job (see below)
start_many(tasks)	start several; partial success is listed per item. Items with id and depends_on form a group (grp-…) run as a DAG without extra turns; foreach=<parent id> makes one copy per item of the parent's .subtask/fanout.json (at most 8), and dependents wait for every copy; after="any" starts when one parent succeeded
integrate(ids, action="apply", auto_resolve=False)	worktree jobs back: diff, apply (all or nothing, uncommitted), discard; auto_resolve starts a reconciliation job on conflict
consensus(prompt, engines, verify_cmd, isolation="worktree")	2 to 4 engines solve it blind in their own worktrees, then one job compares their diffs as anonymous patches and writes one solution, checked by verify_cmd and the invariants; returns a group id
bisect(good_ref, bad_ref, test_cmd, parallelism=4, auto_fix=False)	first commit that makes test_cmd fail, testing up to parallelism (max 8) commits per round in temporary worktrees; returns the commit, author and diff; auto_fix starts a verified fix job
map_reduce(glob_pattern, prompt_template, batch_size=5, concurrency=3, verify_cmd, isolation="worktree")	one job per batch of files ({{files}} in the template), at most concurrency at a time; returns a group id
wait(ids, timeout=300, mode="all", since=None, stall_timeout=None)	block until they end (any: the first; first_success: the first done and verified, the others are stopped); returns early on a stalled job; progress notifications while waiting; since cursor for clients without progress
steer(id, action, instruction=None)	hint (queued, sent as a reply when the attempt ends), abort, retry (fresh job with the instruction)
inspect(id, tail=80, grep=None)	raw log lines, only when the summary is not enough
status(id) / result(id, full, evidence)	one line / summary or full text or JSON envelope
reply(id, message) / stop(id) / cleanup(id)	continue / stop the work / remove a clean worktree (branch kept)
engines()	capacity per engine with source, freshness and confidence, plus spend

Options of start:

• isolation="worktree": own worktree and branch (like repo=), plus SUBTASK_PORT (from 18100), SUBTASK_ID and a private TMPDIR. The result lists files_modified and diff_stat. This also applies to readonly=True; repo= alone keeps read-only jobs in the original directory. The CLI exposes the same choice through start --isolation worktree.
• verify + max_retries: a failed check resumes the job with the output; when every retry fails, a worktree goes back to its best attempt (scored from "N passed / N failed").
• adversarial=True: a Breaker job writes edge-case tests from the spec only; they are copied into the Builder's worktree and run with verify.
• context_refs: file:PATH[:A-B], git:diff[:REF], subtask:ID:summary|diff, resolved before start. auto_repomap=True adds tracked files with their top-level symbols (cached per HEAD).
• invariants (default ["no_test_deletion", "no_suppression"], [] turns them off): before verify counts, test functions may not decrease, no new skip/xfail markers, no new # type: ignore, # noqa or # pragma: no cover. A violation is a failed check with the reason, so a retry sees it.
• allowed_paths: files changed outside these paths are put back and the revert is committed.
• symbol_scope=["path.py::name", ...]: only those top-level functions or classes may change in those files. integrate then merges several jobs' edits to one Python file symbol by symbol; overlaps, import or constant changes, and symbols changed on the target meanwhile are a conflict, never a guess.
• oracle_cmd: after a passing verify, runs the command on the job's base and on its result at the same time and reports whether exit code and stdout match, plus duration_ms_before, duration_ms_after, speedup_pct.
• tier: fast (effort low), deep (effort high, kind hard), free_only. Past 75% of the monthly cap, auto and balanced route automatically selected engines to free engines and the reply carries budget_warning. For these tiers, an explicitly selected paid engine remains allowed with a warning. fast and deep do not change or emit this warning at this threshold. Explicit free_only still rejects paid engines. The monthly cap remains subject to the separate budget admission check.
• Kimi's default K3-256k and supported managed model aliases accept low, high and max effort. Subtask maps medium to high and xhigh to max for those models, which can consume more quota. New sessions retain the effective effort when resumed; custom model aliases keep the requested value.

Memory: when a check fails and a retry fixes it, subtask stores a short lesson for that repository in $SUBTASK_HOME/engrams/ (at most 50, least recently used dropped). Jobs on the same paths get the top three. Groups have a blackboard file for shared notes; new notes show in wait(since=...).

CLI only: subtask board [--json] (the view the OpenCode plugin renders), subtask doctor, gc [--apply], du, roi, routing explain|calibrate, watch ID..., install, uninstall, and --model, --no-sandbox, --untrusted on start.

The gc preview reads recorded job states without settling workers; jobs recorded as active are kept. gc does not calculate file sizes, so its output reports folder counts rather than reclaimed bytes. Run subtask du separately for disk usage; scanning large stores can take time. A copy with files in .reports is kept until a collector leaves a receipt, the regular file .reports/.collected (any content; its mtime must be at least that of the newest report). Empty .reports needs no receipt.

Progress in the chat

client	during a wait
Claude Code 2.1 (TUI)	live line under the tool call, verified
OpenCode 2.0	notifications received, not shown: use wait(since=...)
Kimi Code 2.1	client does not request progress: wait(since=...)
Codex 0.162	not yet verified (account at its usage limit)

Details and evidence: docs/progress-matrix.md.

Settings

variable	default
SUBTASK_HOME	~/.local/share/subtask (jobs, worktrees, ledger, telemetry)
SUBTASK_ENV_FILE	~/.config/subtask/env
SUBTASK_MONTHLY_CAP_USD / SUBTASK_DEFAULT_MAX_USD / SUBTASK_MAX_JOB_USD	180 / 2 / 20
SUBTASK_MAX_RUNNING	4 (global across all processes)
SUBTASK_ROUTING	~/.config/subtask/routing.json (weights, "mode": "legacy")
SUBTASK_JOB_RETENTION_DAYS / SUBTASK_TELEMETRY_DAYS	30 / 90
SUBTASK_PROGRESS_MIN_S / SUBTASK_PROGRESS_HEARTBEAT_S	2 / 10
SUBTASK_CODEX_JOB_HOME	~/.codex-job, used if it has config.toml; otherwise a sanitized ~/.codex-jobs is prepared
SUBTASK_CODEX_KEEP_MCP	unset; set to keep the normal Codex home and its MCP servers

Costs of API engines come from the SDK's estimate; a run whose real cost is unknown is charged its whole reservation. Telemetry stays on this machine. An existing job home is used as-is: its configuration and shared authentication are managed by the operator. An explicit CODEX_HOME takes precedence. For isolated jobs, the chosen home must be an absolute directory narrower than HOME.

Platforms

Linux: supported. macOS: degraded (no /proc start times for liveness, no bwrap: isolated refused). Windows: not supported (fcntl).

Documentation

Architecture · Requirements matrix · Benefits and measurements · Benchmark protocol · Install · Releasing · Contributing

License

MIT