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+, macOS or Linux, and at least one host AI CLI (gh, claude, codex, cursor-agent, junie, or opencode).

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 registry via uvx — works with any MCP-aware host:

claude mcp add threnody -- uvx threnody-mcp
pip install threnody-mcp        # or: python3 -m threnody.mcp_server

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

On first tool call with no config, Threnody returns setup instructions. Run threnody settings to finish.

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 / …)
  → route_task / plan_task   tier + host_spawn / host_spawn_waves
  → host executes            Agent or Task subagents, direct edits
  → utility delegation       execute_subtask → OpenCode / Aider / local (opt-in)
  → swarm / learning         execute_swarm (host_native default), memory_*, learning_*

1. You give a task to your MCP host shell.

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

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 (sonnet) → src/auth.py
📋 Wave 2 — spawn Agent (haiku)  → 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

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.