Threnody

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.

---

What is Threnody?

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.

---

Install

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@threnody

MCP package via uvx or pip — works with any MCP-aware host:

claude mcp add threnody -- uvx threnody-mcp
pip install threnody-mcp
threnody-mcp

The 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://raw.githubusercontent.com/timjensgrossinger/threnody/main/install.sh | bash
# plugin-only (skips shell aliases): ... | bash -s -- --plugin-mode

For 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

---

Compliance posture (defaults)

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.

---

How it works

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_*

1. 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.
2. Threnody scores complexity → low / medium / high tier (no extra LLM call on the hot path).
3. route_task / plan_task return spawn metadata — host_spawn for single-agent, host_spawn_waves for multi-step plans.
4. The host runs the work — Claude Code uses Agent; other shells use Task.
5. Swarms or utility delegation — execute_swarm returns a host-native wave plan by default; execute_subtask only 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.

---

Features

	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
💾	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). Enable per project with threnody tune set learning_enabled true --project ..

---

Project skills

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).

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

---

Supported providers

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

---

See it in action

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

Shell commands

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-watch                                        # live TUI monitor

Full reference: docs/CLI.md

---

Documentation

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

---

Beta status

Public alpha v0.3.0-alpha.2 — 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.

Running tests

THRENODY_TEST_MODE=1 python3 -m pytest tests/ -q
THRENODY_TEST_MODE=1 python3 -m shared.routing_eval
python3 scripts/check_release_archive.py

Uninstall

~/.local/lib/threnody/uninstall.sh [--purge-data]

---

Legal

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.