switchyard

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.

Related MCP server: Delegation MCP

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:

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

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

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.

Supported providers

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 quality --since 7d                           # model quality ledger
threnody ladder run --tier low,medium,high            # graded ground truth (spends tokens)
threnody-watch                                        # live TUI monitor

Full reference: docs/CLI.md

Documentation

Beta status

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.

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.