MCP 服务器

switchyard

Routes coding tasks across multiple AI CLIs (Copilot, Claude Code, Gemini, etc.) with cost-aware tier routing and parallel wave orchestration.

README

<h1 align="center">Threnody</h1> <h3 align="center">Local-first MCP meta-harness — host executes, Threnody coordinates swarms, memory, and learning</h3>

<p align="center"><sub> MCP coordination · self-learning agents · swarm orchestration · cross-session memory · optional delegation </sub></p>

<p align="center"> <strong>Host executes.</strong> Task tool, direct edits, host-configured local/API backends.<br> <strong>Threnody coordinates.</strong> Route, plan, swarm, memory, and approval-gated learning.<br> <strong>Delegate when needed.</strong> Optional subprocess routing to other installed CLIs. </p>

Install in 2 minutes

curl -fsSL https://raw.githubusercontent.com/timjensgrossinger/threnody/main/install.sh | bash

Or clone and install:

git clone https://github.com/timjensgrossinger/threnody.git
cd threnody
./install.sh

Requires: Python 3.10+, macOS or Linux, and at least one host AI CLI (gh, claude, gemini, codex, cursor-agent, junie, or opencode).

Restart your shell, then connect from Claude Code, Copilot CLI, Gemini, Codex, Cursor, or Junie — Threnody registers as an MCP server automatically.

Provider terms: Threnody is not affiliated with or endorsed by any AI provider. Credentials stay in provider-native stores; you configure auth in each host CLI. See docs/LEGAL.md for operator responsibilities.

Docs: limitations · legal · architecture

What is Threnody?

Threnody is a local-first MCP meta-harness for developer workflows. Register it in Claude Code, Copilot CLI, Gemini, Codex, Cursor, or Junie — the host shell executes work while Threnody coordinates routing, planning, swarms, cross-session memory, and approval-gated learned agents.

Optional delegation via execute_subtask routes to other installed CLIs (Copilot, Codex, Cursor, endpoints, Aider, …). Claude Code and Gemini CLI are router-only hosts by default: coordination anchors, not subprocess delegation targets.

Search terms that describe the same project: MCP orchestrator, meta-harness, multi-agent coding, swarm coordination, self-learning agents, Copilot / Claude / Gemini orchestration.

Why Threnody?


Coordinate in the host	`route_task` returns tier guidance and `execution_hint` — host Task tool and direct edits first.
Learn over time	Pattern tracking, draft agents, and an approval queue before anything goes live.
Swarm when needed	Decompose hard work into dependency-ordered waves with linear, DAG, hierarchical, or star topologies.
Delegate optionally	`execute_subtask` routes to other backends when you want cross-CLI execution.

Who this is for

Developers who want MCP coordination (swarms, memory, learning) inside their existing AI CLI host
Teams standardizing on one MCP layer across Copilot, Claude Code, Gemini, Codex, or Cursor
Operators who want local-first state, explicit provider diagnostics, and approval-gated learned agents
Anyone who wants credentials to stay in provider-native stores — Threnody does not manage API keys

Who this is not for

A single chat assistant for casual coding questions — one CLI agent is enough; Threnody adds orchestration overhead
A hosted SaaS with a support SLA — solo open-source project; GitHub issues are how support happens
Compliance-certified agent orchestration — Threnody documents operator responsibilities; it does not ship audit-grade compliance bundles
Non-coding LLM workflows (research, writing, data pipelines) — Threnody wraps CLI coding agents specifically
Anyone who needs Threnody to guarantee provider ToS compliance — your deployment posture depends on which CLIs and routing patterns you enable

Agents that learn — with your approval

Threnody watches recurring work patterns, drafts reusable agents when evidence is strong, and waits for you to approve before anything goes live.

execute subtask → track patterns → draft agent → YOU approve → activate → auto-match future work

No auto-promotion — drafts never become active without explicit approval
Conservative gates — recurrence, quality score, and low rework must all agree before drafting
Project vs shared lanes — project-specific patterns activate sooner; shared patterns need stronger evidence
Inspect everything — learning_agent_summary, learning_pattern_health, and redacted learning_audit_log MCP tools

threnody inspect approvals --project .
threnody inspect approvals approve 12 --project . --operator you

How it works

Host shell (Claude / Copilot / Gemini / …)
  → route_task          tier + execution_hint (host-native first)
  → host executes       Task tool, direct edits, host backends
  → optional delegate   execute_subtask → other CLIs / endpoints
  → swarm / learning    execute_swarm, memory_*, learning_*

You give a task to your MCP host shell.
Threnody scores complexity → low / medium / high tier (no extra LLM call on the hot path).
route_task returns execution_hint — host-native guidance by default; delegation targets when routable backends exist.
Complex tasks decompose into waves — execute_swarm or host Task agents; optional execute_subtask for cross-backend work.

What leaves your machine

By default, Threnody is local-first:

Routing state, telemetry, and caches stay in local SQLite (~/.local/lib/threnody/)
The MCP server talks to your host shell over stdio — no Threnody-hosted control plane
Outbound traffic comes from the provider CLIs you invoke (Anthropic, OpenAI, GitHub, Google, etc.)

If you route to a network LLM endpoint, re-do the network review. See docs/ARCHITECTURE.md and docs/LEGAL.md.

Honest limitations

Threnody orchestrates tools that can execute arbitrary code with your user permissions
Provider risk is real — routing policy reduces it, but cannot change a provider's underlying trust model or terms
Cost rank is a routing hint, not a bill estimate
Realistic enforcement outcome is account suspension or rate limits, not necessarily litigation

Full list: docs/RELEASE_LIMITATIONS.md

Feature highlights

	Feature	What it does
🎯	Tier routing	Heuristic complexity scoring + `execution_hint` for host-native vs delegated work
🧠	Learning loop	Pattern tracking → draft agents → approval queue → auto-match future work
🐝	Swarm orchestration	`execute_swarm` with linear, DAG, hierarchical, and star topologies
💾	Cross-session memory	`memory_*` MCP tools backed by local SQLite
🔌	MCP-native	~43 tools over stdio JSON-RPC; works with any MCP-compatible host shell
🔀	Optional delegation	`execute_subtask` to Copilot, Codex, Cursor, endpoints, Aider, …
📈	Adaptive thresholds	EMA-based threshold learning from routing outcomes
🛡️	Write safety	Path validation, outside-workspace preview gate, audit trail

Supported providers

Provider	Binary	Role	Notes
Claude Code	`claude`	Host (router-only)	MCP coordination anchor; host executes by default
Gemini CLI	`gemini`	Host (router-only)	MCP coordination anchor; host executes by default
GitHub Copilot	`gh`	Host + delegation	Core host; routable for cross-backend work
OpenAI Codex	`codex`	Host + delegation	Host shell + subprocess execution
Cursor	`cursor-agent`	Host + delegation	Host shell + subprocess execution
OpenCode	`opencode`	Delegation	Low-tier auto-route by default
JetBrains Junie	`junie`	Delegation	Medium-tier auto-route by default
Aider	`aider`	Delegation	Secondary adapter
Amazon Q / Kiro	`q` / `kiro`	Delegation	Secondary adapter
Mistral Vibe	`vibe`	Delegation	Secondary adapter
Blackbox AI	`blackbox`	Delegation	When CLI installed
Windsurf	`windsurf`	detect only	Never selected for execution

Run threnody inspect status --project . --details for your live provider matrix.

Full compatibility matrix: docs/PROVIDER_COMPATIBILITY.md

See it in action

Before each wave:

📋 Wave 1 — Foundation files
┌─────────┬──────┬─────────────────────┬──────────────────┬─────────────────────────────┐
│ Agent # │ Tier │ Model               │ Provider         │ Target files                │
├─────────┼──────┼─────────────────────┼──────────────────┼─────────────────────────────┤
│ 1       │ low  │ gpt-5-mini          │ GitHub Copilot   │ config.py                   │
│ 2       │ low  │ gemini-2.5-flash-lite│ Gemini CLI      │ models.py                   │
│ 3       │ med  │ sonnet              │ Claude Code      │ main.py                     │
└─────────┴──────┴─────────────────────┴──────────────────┴─────────────────────────────┘

After all waves:

📊 Build complete — 3 agents, 1 wave
   GitHub Copilot: 1 agent (gpt-5-mini, free)
   Claude Code:    1 agent (sonnet, ~13k tokens)
   Gemini CLI:     1 agent (flash-lite, free)

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
MCP Tools	All 41 MCP tool surfaces
CLI Reference	Shell aliases and operator commands
Architecture	Trust boundaries and local-first design
Configuration	Safe starting config (copy to `~/.local/lib/threnody/config.yaml`)
Model Discovery	Live catalogs, tier pins, cost ranks
Routing Quality	Eval methodology and accuracy
Release Limitations	Beta scope, privacy, roadmap
Legal and Provider Terms	Operator responsibilities and provider links
Troubleshooting	Common fixes

Beta status

Public beta v1.0.0-beta.1 — MCP tool schemas may change between releases; pin a git tag for stability. See CHANGELOG.md.

macOS and Linux; zsh and bash
Windows not supported by the installer
Provider behavior depends on locally installed CLI versions and entitlements

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
~/.local/lib/threnody/uninstall.sh --purge-data

Legal and provider terms

Threnody is an independent open-source project. It is not affiliated with, endorsed by, or sponsored by Anthropic, OpenAI, GitHub, Google, Cursor, JetBrains, or any other provider named in this repository.

Threnody is provided "AS IS" under the Apache License 2.0 (no warranty; limitation of liability). You are solely responsible for determining whether your routing patterns comply with each provider's current terms.

Default execution model: host shells execute via Task tool and direct edits. Claude Code and Gemini CLI are router-only coordination anchors — not default execute_subtask targets. Override only via providers.router_only_allow_execution.

Operator responsibilities and provider links: docs/LEGAL.md

License

Licensed under the Apache License, Version 2.0. Third-party attributions in NOTICE.

Built by @timjensgrossinger.