Lean MCP coordination for host-native swarms, receipts, replayable workflows, and approval-gated learning
host-native execution · token-savings receipts · run cards · workflow blueprints · curated task packs · cross-session memory
Plan in Threnody — route, decompose, swarm via MCP.
Execute in the host — Agent/Task subagents from host_spawn / host_spawn_waves.
Keep receipts — every route, plan, and swarm can return a token-savings receipt and exportable run card.
Replay what works — approved agents and workflow blueprints turn recurring patterns into cheap repeatable flows.
A local-first MCP meta-harness for developer workflows — small, auditable, and host-native, not a hosted swarm platform. Register it in Claude Code, Copilot CLI, Codex, Cursor, Junie, or OpenCode: Threnody plans and routes in MCP; the host shell executes via host_spawn / host_spawn_waves (Agent or Task subagents). When a handoff includes host_spawn_waves, spawn subagents — do not substitute direct edits on planned files.
execute_subtask is utility delegation only (opt-in): OpenCode, Aider, and local loopback endpoints — never other host CLIs. Same-host work returns HostNativeRequired with a spawn payload; host→host delegation returns HostDelegationBlocked. Claude Code is a router-only host by default.
On Claude Code, an opt-in mode (routing_policy.shells.claude-code.workflow_emit) emits tier-aware Dynamic Workflow scripts for fan-out plans — each agent() routes to its Threnody tier model, where a vanilla workflow runs every agent on the session model. Recurring shapes can be approved and saved as permanent /workflow commands.
For operators who want multi-agent coding without a permanent agent army, a second hosted control plane, or hidden coordination-token drift.
Requires: Python 3.10+ and macOS or Linux for the supported installation
paths. The full install.sh workflow expects at least one host AI CLI (gh,
claude, codex, cursor-agent, junie, or opencode); the packaged MCP
server can start without one for setup and diagnostics.
Claude Code plugin marketplace (recommended) — bundles the MCP server and nine routing skills, no shell restart:
claude plugin marketplace add timjensgrossinger/threnody
claude plugin install threnody@threnodyMCP package via uvx or pip — works with any MCP-aware host:
claude mcp add threnody -- uvx threnody-mcp
pip install threnody-mcp
threnody-mcpThe package entry point is a local stdio server. The packaged server can start
for setup and diagnostics without a host CLI; THRENODY_ALLOW_NO_HOST=1 is
only used by the full install.sh workflow to bypass its host-CLI check.
Full CLI install (adds ghc/ghcs/ghce aliases, syncs routing
instructions; restart shell after):
curl -fsSL https://github.com/@raw/timjensgrossinger/threnody/main/install.sh | bash
# plugin-only (skips shell aliases): ... | bash -s -- --plugin-modeFor a configured power-user installation, run threnody settings to finish
setup. The packaged stdio entry point does not run the interactive wizard.
Provider terms: Threnody is not affiliated with or endorsed by any AI provider. Credentials stay in provider-native stores; configure auth in each host CLI. See docs/LEGAL.md.
Docs: plugin install · limitations · legal · architecture
With default config, Threnody matches Anthropic's intended MCP pattern for Claude Code:
| Control | Default behavior |
|---|---|
| Execution | Host runs work via Agent and direct edits — Threnody returns host_spawn / host_spawn_waves, not subprocess loops |
| Router-only | Claude Code is a coordination anchor; not a subprocess backend |
Same-host execute_subtask |
Returns HostNativeRequired with a spawn payload |
| Host→host delegation | HostDelegationBlocked — no subprocess to other CLIs from MCP |
| Utility delegation | Off by default; opt-in targets OpenCode, Aider, and local endpoints only |
| Routing policy | Advisory by default — route_task recommended, not mandatory; opt into guarded for coordination gates (docs/HOOKS.md) |
Operator opt-in risk: Enabling providers.router_only_allow_execution can subprocess Claude Code. With subscription OAuth that pattern is documented as high policy risk in docs/LEGAL.md. Verify your auth mode and provider terms before changing defaults.
Host shell (Claude / Copilot / Codex / Cursor / …)
→ start_task / route_task / plan_task returns next_action and host_spawn_waves for host-native work
→ host executes Agent or Task subagents, direct edits (spawned from host_spawn_waves)
→ utility delegation execute_subtask → OpenCode / Aider / local (opt-in)
→ swarm / learning execute_swarm (host_native default), memory_*, learning_*
- Call the start_task tool (or route_task/plan_task) from your MCP host shell — start_task returns a compact next_action and optional host_spawn_waves for host-native execution.
- Threnody scores complexity → low / medium / high tier (no extra LLM call on the hot path).
Pass
target_filestoroute_taskand the score also reflects the target code's security risk and size, rather than only the wording of the task; omit it and paths named in the task text are used. Security-sensitive work is floored tomedium, and a target holding a high-severity security defect tohigh. route_task/plan_taskreturn spawn metadata —host_spawnfor single-agent,host_spawn_wavesfor multi-step plans.- The host runs the work — Claude Code uses Agent; other shells use Task.
- Swarms or utility delegation —
execute_swarmreturns a host-native wave plan by default;execute_subtaskonly for utility backends when enabled.
Local-first: routing state, telemetry, and caches stay in local SQLite (~/.local/lib/threnody/); the MCP server talks to your host over stdio — no Threnody-hosted control plane. Outbound traffic comes only from the provider CLIs you invoke.
| Feature | What it does | |
|---|---|---|
| 🎯 | Tier routing | Heuristic complexity scoring + host_spawn / execution_hint for host-native work |
| 🧠 | Learning loop | Pattern tracking → draft agents → approval queue → plan-time context injection. No auto-promotion; conservative recurrence/quality/rework gates |
| 🐝 | Swarm orchestration | execute_swarm returns host_spawn_waves by default; broad reviews default to one agent per file, deep review opts into file × dimension fanout; parallelism.max_workers throttles concurrency separately from plan size |
| ⚡ | Dynamic Workflows | Opt-in (claude-code): fan-out plans emit a tier-aware Workflow script; recurring shapes export to permanent /workflow commands |
| 🧾 | Receipts and run cards | cost_receipt + inspect_run_receipt(format=json|markdown|html) record plan, waves, model rationale, skipped calls, policy decisions, outcomes |
| 🧩 | Task packs and blueprints | Curated packs (security-review, test-gap, release-check); successful runs export to replayable workflow blueprints |
| 🔬 | Static pre-scan | Deterministic AST + pattern scan (zero tokens) sharpens review tiering, injects verified-or-refuted leads, and grades reviewers against ground truth |
| ♻️ | Prior-review memory | An unchanged (file revision × dimension) already covered at an equal-or-stronger tier is skipped and replayed; findings since fixed are suppressed |
| 🪄 | Hybrid diagnose→implement | One read-only high-tier diagnosis produces a change-spec, cheaper implementers execute it. Emits tiers only; the discount is learned per work profile, never hardcoded |
| ✅ | Baseline-diff verify gate | Lint/type/test graded against the merge base, so pre-existing red never blocks and only real regressions get a fix pass (in-process, zero tokens on the host path) |
| 📚 | Repo beliefs | Each run leaves a free pattern/constraint lesson; later runs get the most relevant ones injected, ranked by SQLite FTS × recency × recurrence (no embeddings) |
| 🪜 | Graded task ladder | threnody ladder run executes benchmark cases with deterministic graders on two axes: difficulty (L0–L6) and task kind (xss-fix, boilerplate-crud, refactor, …). Derives the minimum passing tier per model on each — so "which model is good at what" comes from graded outcomes rather than a hand-maintained mapping. Security cases use exploit-style graders that feed real payloads |
| 💾 | Cross-session memory | memory_* MCP tools backed by local SQLite, shared across all MCP hosts |
| 🔌 | MCP-native | 53 published tools over stdio JSON-RPC; works with any MCP-compatible host |
| 📈 | Adaptive thresholds | EMA threshold learning from record_outcome (per-project, opt-in) |
| 🛡️ | Write safety | Path validation, outside-workspace grant model + audit trail |
| 🔒 | Guarded routing | Optional coordination gate + Claude PreToolUse hooks (routing_policy.mode: guarded) |
Cross-CLI memory: all hosts share one SQLite store at ~/.local/lib/threnody/cache.db. Use global (no project_id), project (pass a stable absolute path, not "."), or task (explicit task_id) scopes. Do not store secrets — any connected host can read keys.
Adaptive routing: route_task returns a task_id; after work, call record_outcome(task_id=…, outcome=accepted|revised|rejected|reworked, actual_model=…) (also recorded as a proxy outcome score in the quality ledger). Enable per project with threnody tune set learning_enabled true --project ..
Nine repo-local skills under skills/ guide MCP workflows from any host. install.sh installs them into provider-native roots (directory-style for Claude Code / Cursor / Codex; flat markdown for Copilot CLI / OpenCode).
install.sh also writes the five review-dimension agent definitions into each host's own definition directory, so a review fan-out does not repeat the same checklist in every agent prompt (prompt_economy.externalize_boilerplate). A definition you already have under the same name is never overwritten — your tuned reviewer is the better version of that file.
| Skill | Use when |
|---|---|
| threnody-plan | Plan-only or plan-then-execute; waves vs swarm |
| threnody-routing | route_task, routing guard, host-native vs utility delegation |
| threnody-task | plan_task, decompose_task, fleet_plan, host_spawn_waves |
| threnody-swarm | execute_swarm, topology, budget preview, resume |
| threnody-fast-review | Default broad review swarm — one read-only agent per file plus synthesis |
| threnody-swarm-review | Deep review swarm — file × dimension fanout, optional [dims=...], ranked report |
| threnody-workflow | Claude Code tier-aware Dynamic Workflows; save /workflow commands |
| threnody-fullstack | Contract-first parallel frontend + backend + API |
| threnody-subtasks | Monitor opt-in utility execute_subtask runs |
| Provider | Binary | Role |
|---|---|---|
| Claude Code | claude |
Host (router-only) — executes via Agent / direct edits |
| GitHub Copilot | gh |
Host — executes via Task |
| OpenAI Codex | codex |
Host — Task execution |
| Cursor | cursor-agent |
Host — Task execution |
| OpenCode | opencode |
Host + utility delegation target |
| JetBrains Junie | junie |
Host / legacy paths |
| Aider | aider |
Utility (opt-in delegation) |
| Amazon Q / Kiro · Mistral Vibe · Blackbox | q/kiro/vibe/blackbox |
Secondary adapters / detect |
| Windsurf | windsurf |
Detect only — never executes |
Live matrix: threnody inspect status --project . --details. Full table: docs/PROVIDER_COMPATIBILITY.md
plan_task("add JWT auth with tests")
→ host_spawn_waves: [
{ "wave": 1, "agents": [{ "tool": "Agent", "tier": "medium", "target_files": ["src/auth.py"] }] },
{ "wave": 2, "agents": [{ "tool": "Agent", "tier": "low", "target_files": ["tests/test_auth.py"] }] }
]📋 Wave 1 — spawn Agent (host model) → src/auth.py
📋 Wave 2 — spawn Agent (host model) → tests/test_auth.py
Optional utility delegation (opt-in via providers.delegation_utilities_enabled):
execute_subtask(prompt="…", tier="low", provider_id="opencode") → OpenCode utility backend
execute_subtask(prompt="…", tier="medium") → HostNativeRequired + spawn payload
execute_subtask(provider_id="codex") → HostDelegationBlocked
ghc agent "implement JWT auth for the user service" # multi-agent waves
ghcs "how to list files recursively in python" # quick routed call
threnody inspect status --project . --details # provider readiness
threnody quality --since 7d # model quality ledger
threnody ladder run --tier low,medium,high # graded ground truth (spends tokens)
threnody ladder run --provider codex # grade another host's tier models; in Claude Code use /threnody-ladder
threnody ladder run --stale # re-grade only tiers whose model changed
threnody db learn status # durable learning journal + table counts
threnody db learn rebuild # rebuild the DB's learning tables from the journal
threnody-watch # live TUI monitorFull reference: docs/CLI.md
| Doc | Contents |
|---|---|
| Plugin Install | uvx, plugin marketplace, --plugin-mode |
| MCP Tools | All 53 MCP tool surfaces |
| CLI Reference | Shell aliases and operator commands |
| Architecture | Trust boundaries and local-first design |
| Configuration | Safe starting config |
| Routing Quality | Eval methodology and accuracy |
| Host routing hooks | Claude PreToolUse guard script |
| Cost savings | Host-native vs utility delegation |
| Competitive positioning | Threnody vs heavy swarm platforms |
| Release Limitations | Beta scope, privacy, roadmap |
| Legal and Provider Terms | Operator responsibilities |
| Troubleshooting | Common fixes |
Public alpha v0.3.0-alpha.3 — MCP tool schemas may change between releases; pin a git tag for stability. macOS and Linux (zsh/bash); Windows not supported by the installer. See CHANGELOG.md.
THRENODY_TEST_MODE=1 python3 -m pytest tests/ -q
THRENODY_TEST_MODE=1 python3 -m shared.routing_eval
python3 scripts/check_release_archive.py~/.local/lib/threnody/uninstall.sh [--purge-data]Threnody is an independent open-source project, not affiliated with or endorsed by Anthropic, OpenAI, GitHub, Google, Cursor, JetBrains, or any other provider named here. Provided "AS IS" under the Apache License 2.0 (no warranty). You are solely responsible for determining whether your routing patterns comply with each provider's current terms.
Operator responsibilities: docs/LEGAL.md · Third-party attributions: NOTICE
Built by @timjensgrossinger.