convez.ai
MCP ServerAutomaçãoAvançado
timjensgrossinger

Threnody — Orquestrador MCP consciente de custo

timjensgrossinger/threnody

Orquestre múltiplos agentes de IA com swarms, memória e custo controlado

Ver no GitHub
InicialPluginScore · de 0 a 100

Meta-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/threnody

1 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

Estrelas
2
Forks
0
Acompanhando
0
Saúde
71%
Último commit
há 1 mês
Versão
v0.3.0-alpha.1
Issues abertas
0
Contribuidores
2

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 hostroute_task returns tier guidance and execution_hint — host Task tool and direct edits first.
Learn over timePattern tracking, draft agents, and an approval queue before anything goes live.
Swarm when neededDecompose hard work into dependency-ordered waves with linear, DAG, hierarchical, or star topologies.
Delegate optionallyexecute_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_*
  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 returns execution_hint — host-native guidance by default; delegation targets when routable backends exist.
  4. 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

FeatureWhat it does
🎯Tier routingHeuristic complexity scoring + execution_hint for host-native vs delegated work
🧠Learning loopPattern tracking → draft agents → approval queue → auto-match future work
🐝Swarm orchestrationexecute_swarm with linear, DAG, hierarchical, and star topologies
💾Cross-session memorymemory_* MCP tools backed by local SQLite
🔌MCP-native~43 tools over stdio JSON-RPC; works with any MCP-compatible host shell
🔀Optional delegationexecute_subtask to Copilot, Codex, Cursor, endpoints, Aider, …
📈Adaptive thresholdsEMA-based threshold learning from routing outcomes
🛡️Write safetyPath validation, outside-workspace preview gate, audit trail

Supported providers

ProviderBinaryRoleNotes
Claude CodeclaudeHost (router-only)MCP coordination anchor; host executes by default
Gemini CLIgeminiHost (router-only)MCP coordination anchor; host executes by default
GitHub CopilotghHost + delegationCore host; routable for cross-backend work
OpenAI CodexcodexHost + delegationHost shell + subprocess execution
Cursorcursor-agentHost + delegationHost shell + subprocess execution
OpenCodeopencodeDelegationLow-tier auto-route by default
JetBrains JuniejunieDelegationMedium-tier auto-route by default
AideraiderDelegationSecondary adapter
Amazon Q / Kiroq / kiroDelegationSecondary adapter
Mistral VibevibeDelegationSecondary adapter
Blackbox AIblackboxDelegationWhen CLI installed
Windsurfwindsurfdetect onlyNever 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

DocContents
MCP ToolsAll 41 MCP tool surfaces
CLI ReferenceShell aliases and operator commands
ArchitectureTrust boundaries and local-first design
ConfigurationSafe starting config (copy to ~/.local/lib/threnody/config.yaml)
Model DiscoveryLive catalogs, tier pins, cost ranks
Routing QualityEval methodology and accuracy
Release LimitationsBeta scope, privacy, roadmap
Legal and Provider TermsOperator responsibilities and provider links
TroubleshootingCommon 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.

Ver o original no GitHub

Bom para

Relacionados