io.github.tedin7Published by GitHub account tedin7v0.5.9Updated Nov 4, 2026
Background sub-agents for Claude Code, Codex, Kimi and OpenCode, over MCP, with a spend cap.
subtask's local MCP server; no sign-in required; STDIO; 18 tools.
No AI overview yet: these facts come from the registry entry and the server itself.
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Follow the launch instructions in the repository.
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 + one wait replace a polling loop.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).verify="..." runs your check on the commit the
worker left; result(evidence=True) separates what subtask observed from
what the worker reported.The distribution is subtask-mcp (the PyPI name subtask is an unrelated
project). Full guide, per client, with native commands: docs/install.md.
Jev provides advisory workflow checks automatically, or only when requested:
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).
Add an engine without touching the core: an EngineAdapter registered under the
subtask.engines entry point (see CONTRIBUTING.md).
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.
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.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 go to free engines and the reply carries budget_warning.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.
Details and evidence: docs/progress-matrix.md.
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.
Linux: supported. macOS: degraded (no /proc start times for liveness, no
bwrap: isolated refused). Windows: not supported (fcntl).
Architecture · Requirements matrix · Benefits and measurements · Benchmark protocol · Install · Releasing · Contributing
MIT
Source: README.md at commit 5d936a1
Preview tasks before workers start. Read deterministic facts and advisory Jev contradictions, then launch=True with plan_id to start the unchanged plan once. Changed inputs require a new preview. This is a coordinator decision within the authorized task, not a new operator permission. Legacy start/start_many remain available. Read dependencies must be explicit in depends_on.
taskslaunchplan_idStart one job; returns its id. kind: read|code|review|hard. Writes: repo= or isolation='worktree' (own branch). model: engine-specific model id (opencode, codex, kimi, API engines); omitted = the engine's default. verify: shell check run by subtask after the job; max_retries (0-5) resumes with the failure. invariants: default ['no_test_deletion','no_suppression'] fail verify on deleted/skipped tests or new noqa; [] = off. allowed_paths: files outside are reverted. symbol_scope: ['f.py::func'] only those defs may change; integrate merges by symbol. oracle_cmd: after verify passes, run on base and result; reports output_match and speedup_pct. adversarial: a Breaker job writes the tests first. context_refs: file:P[:A-B] | git:diff[:REF] | subtask:ID:summary|diff instead of pasting text; auto_repomap adds a symbol map. policy: worktree|sandbox|isolated|untrusted. tier: auto|fast|balanced|deep|free_only.
cwdbasekindrepotaskrequiredtierfilesmodeleffortenginepolicyverify+13 moreStart several jobs in one call. Items take start()'s arguments. With id + depends_on they form a group (grp-…) run as a DAG; subtask:<id>:summary in task/context_refs is replaced by the real job id. With Jev auto, the response includes advisory dependency checks; read them without treating them as permission. foreach=<parent id>: one copy per item of the JSON list the parent writes to .subtask/fanout.json ({{item}} in task), max 8; dependents wait for every copy. after='any': start when one parent succeeded.
tasksrequiredBlock until jobs or groups end and return their summaries. mode: all | any (first to end) | first_success (first done and verified; the rest are stopped). Returns early on a stalled job. since: cursor for clients without progress; with it, timeout is capped at 60 s. For Codex: wait(ids, mode='any', timeout=60, since=''), drop ended ids and pass back cursor=. An idle Codex 0.164.0 is not woken by ordinary local MCP progress or log notifications. Includes the automatic Jev delivery/evidence/risk advice, raw provider choice, wrapper assessment and next action: read it before a manual review and do not resubmit the same work.
anyidsrequiredmodesincetimeoutstall_timeoutOne line per job.
idJob summary; full=True for all; evidence=True for the JSON envelope.
idrequiredfullevidenceJev auto adds advisory feedback checks; read the output. Continue a finished job.
idrequiredmessagerequiredStop a job.
idrequiredCorrect a job: hint (instruction sent when the attempt ends) | abort | retry (fresh job with the instruction).
idrequiredactionrequiredinstructionShow or change the shared Jev policy: status | auto | manual | off. Only the operator changes the policy: do not switch it to obtain or avoid a check. Auto checks every new final delivery once within the existing budget; read that outcome in wait()/result before any manual review. All advice is consultative. Credentials are never accepted here: add or replace a key in a terminal with `subtask jev setup` (hidden input), never in chat, argv or a tool argument. Changes apply to new submissions in every configured CLI; no server reload is needed.
actionAdvisory Jev review of a terminal delivery against the parent's criteria (1-12). Read the automatic outcome in wait()/result first; do not resubmit the same delivery. Default prepares a local evidence packet without network; packets=True prepares separate claim packets and manifests offline (never submits). submit=True sends one request (unknown sends are never retried). Supply original_request from the coordinator to judge full scope; without it scope_assessment is unproven, which is neither a pass nor a contradiction. supported is advice, not acceptance. provider_choice is the raw answer; assessment includes local vetoes (missing, failed or mismatched evidence), which are not findings by the model. Jev never accepts, merges, deploys or retries the worker; local checks remain necessary. Key/budget errors are final for the call: keys only from `subtask jev setup`, never a tool argument.
idrequiredsubmitpacketscriteriarequiredoriginal_requestRaw log lines of a job (last `tail`, filtered by `grep`). Only when the summary is not enough.
idrequiredgreptailBring worktree jobs back. diff first to review; apply = uncommitted, all or nothing, Python files of symbol_scope jobs merged by symbol; discard removes worktree and branch. auto_resolve: a reconcile job on conflict.
idsrequiredactionauto_resolveFirst commit in good_ref..bad_ref that fails test_cmd, testing up to parallelism commits at once. auto_fix: start a fix job.
repobad_refrequiredauto_fixgood_refrequiredtest_cmdrequiredparallelism2-4 engines solve prompt blind in worktrees, then one job merges the best (verify, invariants). Returns a group id for wait().
repopromptrequiredenginesrequiredmax_usdisolationverify_cmdThe same edit over many files: one job per batch of files matching glob ({{files}} in prompt_template), at most `concurrency` at once, each in a worktree with verify_cmd. Returns a group id for wait().
cwdrepoengineisolationbatch_sizeverify_cmdconcurrencyglob_patternrequiredprompt_templaterequiredRemove a job's worktree, keep branch.
idrequiredFree quota and API spend.
Takes no parameters.
90% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
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 · readonlywait(["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, costuv tool install "git+https://github.com/tedin7/subtask@main" # or: uv tool install /path/to/checkoutsubtask install --client all # prints the plan for every detected clientsubtask install --client all --yes # applies it: MCP server + skillsubtask doctor --client all # checks app, config entry and a real handshakesubtask jev # policy, key availability and the current process's budget limitssubtask jev setup # guided setup; key input is hiddensubtask jev auto # automatic routing, feedback and final delivery advicesubtask jev manual # explicit review submissions onlysubtask jev off # block new Jev submissions