Threnody — Orquestrador MCP consciente de custo
timjensgrossinger/threnody
Orquestre múltiplos agentes de IA com swarms, memória e custo controlado
Ver no GitHubMeta-harness MCP local-first que coordena swarms de agentes, memória cross-session e roteamento inteligente entre CLIs de IA (Claude, Copilot, Gemini, Cursor). Executa no host, aprende com aprovação e delega tarefas opcionalmente para outros CLIs instalados.
Instalação
npx convez-ai timjensgrossinger/threnody1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Coordenar fluxos de trabalho complexos entre Claude, Copilot e Gemini
- Treinar agentes auto-aprendíveis com fila de aprovação
- Decompor tarefas em swarms com topologias DAG ou hierárquicas
- Manter memória de contexto entre sessões de coding
Veredito

Threnody é uma solução madura e ambiciosa para quem precisa orquestrar múltiplos agentes de IA em fluxos complexos. Beta-ready com instalação simples, mas exige familiaridade com MCP, Python 3.10+ e múltiplas CLIs — ideal para equipes de desenvolvimento que querem automação multi-agente com controle e aprendizado progressivo.
README
A tradução para o português deste README ainda está na fila.
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 redactedlearning_audit_logMCP 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_taskreturnsexecution_hint— host-native guidance by default; delegation targets when routable backends exist.- Complex tasks decompose into waves —
execute_swarmor host Task agents; optionalexecute_subtaskfor 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;
zshandbash - 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.