nexus-agents
Plataforma de orquestração inteligente que roteia tarefas para o melhor modelo de IA (Claude, Codex, Gemini, OpenCode) usando bandidos LinUCB, valida por votação de consenso e aprende com os resultados. 29 ferramentas MCP, pipeline de desenvolvimento, 8 backends de memória.
Documentação
Nexus Agents
Plano de controle autonômico para agentes de codificação de IA — um único ponto de entrada, revisão adversarial, auditoria com encadeamento hash à prova de adulteração, ajuste de malha fechada com gate humano (rebaixamento autônomo, promoção conquistada)
Por que Nexus Agents?
Nexus-agents é um plano de controle autonômico para seus agentes de codificação de IA — Claude Code, Codex, Gemini e OpenCode. Os agentes são o plano de dados: eles fazem a engenharia. Nexus-agents é o plano de controle: ele admite o trabalho por um único ponto de entrada, revisa-o adversarialmente antes de ser entregue, registra cada ação em um log de eventos à prova de adulteração e fecha o ciclo ajustando para onde a próxima tarefa vai com base no que realmente funcionou.
Tomando emprestado o vocabulário da computação autonômica: o sistema executa um loop MAPE-K — Monitorar, Analisar, Planejar, Executar sobre uma base de conhecimento compartilhada — para que operar sua frota de agentes seja, tanto quanto as evidências permitirem, autogerenciável em vez de conduzido manualmente.
O mapeamento do plano de controle
Cada papel clássico do plano de controle mapeia para um componente entregue do nexus-agents — a metáfora é estrutural, não decorativa:
| Papel no plano de controle | Componente nexus-agents | O que faz |
|---|---|---|
| Agendador | run / MetaOrchestrator | Um único ponto de entrada escolhe (e opcionalmente executa) a estratégia certa para um objetivo |
| Controle de admissão | gates (pr_review, consensus_vote, run_quality_gate) | Revisão adversarial e gates de qualidade decidem o que pode ser entregue |
| Log de eventos | AuditTrail cadeia hash + verify_audit_chain | Registro somente-acréscimo e à prova de adulteração de cada decisão |
| Plano de dados | CLIs de engenharia | Claude Code, Codex, Gemini, OpenCode fazem as edições de arquivos, testes, PRs |
O loop MAPE-K
┌────────── Monitor ──────────┐ OutcomeStore · AuditTrail · swarm-health
│ ▼ adapter circuit-breaker signals
Execute ◀── Plan ◀── Analyze ◀───┘ LinUCB + TOPSIS scoring, consensus
│ │ MetaOrchestrator strategy choice
│ └── route the next task ──────────────────────────────────────┐
▼ │
run the strategy ── adversarial review ── audit ── feed outcome back ──────┘
shared Knowledge: OutcomeStore + memory backends + audit log
Capacidades self-*
Sistemas autonômicos são descritos por suas propriedades self-*. Cada linha abaixo mapeia para um loop que existe no código hoje — nada aqui é aspiracional, e a autoridade que cada loop carrega é limitada pela escada de autoridade do ADR-0017 (observe → suggest → advisory → enforce):
| Propriedade self-* | O que significa aqui | Loop implementado (entregue) |
|---|---|---|
| Autoconfigurável | Detecta o ambiente e se integra | nexus-agents setup / doctor (cli-commands.ts) — detecta CLIs, escreve configuração MCP, reporta saúde |
| Autocura | Roteia ao redor de dependências com falha automaticamente | Disjuntor de adaptador + rebaixamento por saúde do enxame (cli-adapters/circuit-breaker.ts); um ajuste TuneAdjustmentStore limitado, com decaimento automático e somente-rebaixamento |
| Auto-otimização | Aprende para onde a próxima tarefa deve ir | Loop fechado OutcomeStore → pontuação LinUCB + TOPSIS no CompositeRouter |
| Autoproteção | Restringe o que entrada não confiável e ferramentas podem fazer | Tratamento de entrada por níveis de confiança, relatório de política de acesso ClawGuard (consultivo), sandboxing Docker/política (security/) |
Nota de honestidade: esses loops estão em diferentes degraus da escada de autoridade. O rebaixamento por autoajuste é
enforcemas limitado (limitado, com decaimento automático, somente-rebaixamento); a seleção aprendida e outras promoções ainda são conquistadas por loop contra um limite de evidências mais ratificação, não ativadas por padrão. Veja ADR-0017.
O que isso oferece:
- Revisão adversarial de PR —
pr_reviewexecuta 5 papéis de votação (arquiteto, segurança, devex, catfish, scope_steward) com um gate de verificação de 4 pontos. No conjunto de avaliação v5: 100% de captura de bugs em um conjunto de dados sintético focado (n=10) e uma taxa bruta de falsos positivos de 50%; a triagem manual reclassificou um dos dois casos de FP inspecionados como um achado real que o conjunto de dados havia rotulado incorretamente. Esses são números direcionais de amostra pequena, não taxas medidas. Números completos e salvaguardas: docs/research/pr-review-experiment-results-v5.md - Charter com detecção de desvio —
CLAUDE.md+governance:check+ gates de CI bloqueantes falham o build quando regras documentadas se desviam do comportamento registrado (registro de modelos, ferramentas MCP, tipos de especialistas, habilidades) - Trilha de auditoria à prova de adulteração — cada chamada de ferramenta, cada decisão de votação, cada escolha de roteamento flui através do
AuditTrailcom logging estruturado e armazenamento somente-acréscimo com encadeamento hash; a integridade é verificável via a ferramenta MCPverify_audit_chain(à prova de adulteração, não à prova de adulteração absoluta — veja o modelo de ameaça da cadeia hash de auditoria) - Roteamento de malha fechada —
OutcomeStorealimenta telemetria de produção de volta na pontuação LinUCB + TOPSIS para que o sistema realmente aprenda com o que foi entregue vs o que regrediu. Um segundo loop limitado é executado por padrão: umsignal.swarm_unhealthy(disjuntor de adaptador / saúde do enxame) aplica um pequeno rebaixamento de roteamento limitado e com decaimento automático viaTuneAdjustmentStore— somente-rebaixamento, nunca zera um CLI, cada ajuste é auditado, opt-out comNEXUS_TUNE_ENFORCE=false - Consenso multi-votante —
consensus_voteexecuta um painel padrão de 7 papéis (arquiteto, segurança, devex, ai_ml, pm, catfish, scope_steward;--quickusa 3). Seis nomes de estratégia (cinco distintos:higher_orderé um alias deopinion_wise, #514): maioria simples/supermaioria, unanimidade, Bayesiano de ordem superior, por opinião, prova-de-aprendizado
You: "Review this PR / orchestrate this task / vote on this proposal"
↓
Control plane: admit → schedule/route → adversarial review → audit → learn from outcome
↓
Data plane (agents): Claude Code · Codex · Gemini · OpenCode
↓
Code: actual edits, tests, PRs, issues
O que isso NÃO é:
- Não é outro agente de codificação autônomo. OpenHands, SWE-agent, AutoGen, Devin, Factory — esses são o plano de dados. Nexus-agents é o plano de controle acima deles. Use quaisquer agentes que se adequem; nós admitimos, revisamos, auditamos e roteamos o trabalho deles
- Não é um framework de chat. Nada aqui orquestra conversas. Orquestra invocações reais de CLI com I/O real de arquivos e rastreamento de resultados
- Não é um proxy de API de modelo. O valor está nos gates de admissão, na auditoria e no ajuste de malha fechada. O roteamento é uma consequência do trabalho do plano de controle, não o produto
- Não é totalmente autônomo. "Autonômico" significa autogerenciável dentro de limites, não supervisionado. A autoridade de cada loop é limitada pela escada de autoridade (ADR-0017); promoções para autoridade maior são conquistadas contra evidências e ratificação humana, nunca ativadas por padrão
Onde o nexus-agents se encaixa na sua stack
Human / IDE / CLI
(Claude Code, Cursor, VS Code, terminal)
│ MCP Protocol
▼
┌─────────────────────────────────────────────────────┐
│ CONTROL PLANE — what nexus-agents provides │
│ │
│ Scheduler: run / MetaOrchestrator │
│ Admission control: PR review · consensus · gates │
│ Event log: tamper-evident hash-chained audit │
│ Closed-loop self-tuning (MAPE-K) │
│ │
│ 47 MCP tools · multi-stage CompositeRouter │
└────────────────────────┬────────────────────────────┘
│
▼ delegates execution to
┌─────────────────────────────────────────────────────┐
│ DATA PLANE — the agents that do the actual work │
│ │
│ Claude Code · Codex · Gemini · OpenCode │
└────────────────────────┬────────────────────────────┘
│
▼ produces
Code, tests, PRs, issues
O plano de controle é a camada que captura os erros que os agentes do plano de dados cometeriam — código ruim entregue, regras se desviando da intenção, lacunas de auditoria, roteamento sem telemetria — e roteia a próxima tarefa com base no que realmente funcionou da última vez.
Início Rápido (2 minutos)
1. Instalar
npm install -g nexus-agents
Ou como plugin do Claude Code (instalação com um comando do marketplace oficial):
/plugin install nexus-agents
Veja docs/getting-started/PLUGIN_INSTALL.md para configuração específica do plugin, ou llms-install.md para o guia curto de instalação que um agente de IA pode seguir.
2. Verificar
nexus-agents doctor
Imprime uma tabela de saúde — versão do Node, CLIs configurados (claude / codex / gemini / opencode), chaves de API ausentes vs presentes. Somente leitura; seguro de executar a qualquer momento.
3. Veja como é o sucesso (tarefa de fumaça de 60 segundos — sem necessidade de chaves de API)
nexus-agents vote --quick --proposal "Use SQLite over JSON files for the outcome store"
Você deve ver:
Nexus Agents Consensus Vote
============================
Collecting votes from 3 agents (timeout: 60s each)...
Proposal: Use SQLite over JSON files for the outcome store
Votes
✓ Software Architect: APPROVE (86%)
✓ Security Engineer: APPROVE (74%)
✓ Scope Steward: APPROVE (91%)
Summary
Approve: 3
Reject: 0
Abstain: 0
Approval: 100.0%
Threshold: simple_majority
Result: APPROVED
Completed in ~30s
Três papéis de votação deliberam via quaisquer CLIs locais que você tiver (Claude, Codex, Gemini) — sem necessidade de chaves de API. O raciocínio de cada votante é registrado; o terminal imprime o veredito. Resultados mistos (alguns aprovam / alguns rejeitam) e tratamento gracioso de erros são demonstrados no hero do site do projeto com uma execução real de 7 votantes.
4. Integre ao seu editor
nexus-agents setup # Auto-configures MCP server in Claude Code, Cursor, etc.
Reinicie seu editor. As 47 ferramentas MCP (orchestrate, consensus_vote, research_synthesize, verify_audit_chain, …) ficam disponíveis para qualquer agente que você já esteja usando.
O que o setup configura
Por padrão, o setup escreve/atualiza até sete coisas no seu ambiente. Cada uma pode ser ignorada com a flag --skip-* correspondente se você não quiser.
| Configurado | Onde é escrito | Flag de opt-out |
|---|---|---|
| Registro do servidor MCP (Claude) | ~/.claude/mcp.json / config do Claude Desktop | --skip-mcp |
| Regras do projeto | .cursor/rules/ e/ou .claude/rules/ | --skip-rules |
| Hooks de sessão | ~/.claude/hooks/ (início-de-sessão / pré-ferramenta / etc.) | --skip-hooks |
| Config MCP do OpenCode | ~/.config/opencode/opencode.json | --skip-opencode |
| Config MCP do Gemini | ~/.gemini/mcp.json | --skip-gemini |
| Config MCP do Codex | ~/.codex/config.toml | --skip-codex |
| Arquivo de configuração do projeto | ./nexus-agents.yaml | --skip-config |
Execute com --interactive (o padrão) para um fluxo de confirmação passo a passo, ou --no-interactive para aceitar todos os padrões.
5. Uso autônomo (sem necessidade de editor)
export ANTHROPIC_API_KEY=your-key
nexus-agents orchestrate "Explain the architecture of this codebase"
Segurança: No modo MCP padrão, o servidor se comunica apenas via stdio com o processo pai (sem exposição de rede). A API REST (opt-in) gera automaticamente uma chave de API no primeiro início. Para implantações expostas à rede, defina
NEXUS_AUTH_ENABLED=true. Veja SECURITY.md.
Capacidades
| Categoria | Detalhes |
|---|---|
| Revisão Adversarial de PR | pr_review Ferramenta MCP: 5 papéis de votação (arquiteto, segurança, desenvolvedor, catfish, guardião de escopo) com gate de 4 pontos. Avaliação v5 (conjunto de dados sintético focado, n=10): 100% de captura de bugs, 50% de taxa bruta de falsos positivos; triagem manual reclassificou um dos dois casos de FP inspecionados como um achado real (direcional com n pequeno, não taxas medidas) (detalhes) |
| Votação por Consenso | 6 estratégias: maioria simples, supermaioria, unanimidade, ordem superior (Bayesiana ciente de correlação), opinião sábia, prova de aprendizado |
| Carta com Detecção de Deriva | CLAUDE.md + inject-governance.ts check impõe registros de fonte única (registro de modelos, ferramentas MCP, tipos de especialistas). Gate de CI bloqueante falha o build em caso de deriva |
| Trilha de Auditoria | Logging estruturado para cada chamada de ferramenta, decisão de votação e escolha de roteamento. Armazenamento anexado com hash encadeado e à prova de adulteração (à prova de adulteração, não à prova de violação — veja modelo de ameaça); integridade verificável via ferramenta MCP verify_audit_chain |
| Telemetria de Ciclo Fechado | OutcomeStore alimenta a pontuação LinUCB + TOPSIS; um segundo loop de autoajuste limitado e auditado rebaixa CLIs não saudáveis (limitado, com decaimento automático, ativado por padrão, com opt-out NEXUS_TUNE_ENFORCE=false) |
| Pipeline de Segurança | Sandboxing (Docker/política), tratamento de entrada por níveis de confiança, parsing SARIF, padrões de red-team, relatórios de política de acesso ClawGuard (consultivo) |
| Orquestração Multi-Especialista | 12 tipos de especialistas integrados coordenados pelo Orquestrador. Papéis vinculam prompt + ferramentas + memória |
| Pipeline de Desenvolvimento | Pesquisa → Plano → Voto → Decomposição → Implementação → QA → Segurança. Três modos: autônomo, harness (chamador implementa), dry-run |
| Memória e Aprendizado | 5 backends voltados ao usuário (sessão, crença, agêntico, adaptativo, tipado). Persistência entre sessões alimenta decisões de roteamento |
| Sistema de Pesquisa | 9 fontes de descoberta (arXiv, GitHub, Semantic Scholar, etc). Auto-catálogo, pontuação de qualidade, síntese em clusters de tópicos |
| Fluxos de Trabalho em Grafo | Execução de fluxo de trabalho baseada em DAG com checkpoint/retomada, redução de estado e hooks de eventos |
| 47 Ferramentas MCP | Gerenciamento de agentes, execução de fluxo de trabalho, pesquisa, memória, inteligência de código, análise de repositório, consenso, operações |
Especialistas Disponíveis
| Especialista | Especialização |
|---|---|
| Código | Implementação, depuração, otimização |
| Arquitetura | Design de sistemas, padrões, escalabilidade |
| Segurança | Análise de vulnerabilidades, codificação segura |
| Testes | Estratégias de teste, cobertura, geração de testes |
| QA | Critérios de aceitação, verificações de regressão |
| Documentação | Escrita técnica, docs de API |
| DevOps | CI/CD, implantação, infraestrutura |
| Pesquisa | Revisão de literatura, análise de estado da arte |
| PM | Gestão de produto, requisitos, prioridades |
| UX | Experiência do usuário, usabilidade, acessibilidade |
| Infraestrutura | Gerenciamento de servidores, bare metal, redes |
| Visualização de Dados | Gráficos, dashboards, apresentação visual de dados |
CLIs e Provedores Suportados
Nexus-agents roteia tarefas por 4 adaptadores CLI, cada um conectando-se aos principais provedores de IA:
| CLI | Provedor | Melhor Para |
|---|---|---|
| claude | Anthropic (Claude) | Raciocínio complexo, análise |
| gemini | Google (Gemini) | Contexto longo, multimodal |
| codex | OpenAI (Codex) | Geração de código, raciocínio |
| opencode | Compatível com OpenAI personalizado | Endpoints personalizados, modelos locais |
codex tem dois transportes, selecionados por configuração em vez de por nome:
CodexMcpAdapter (o padrão, nativo do MCP) e CodexCliAdapter (subprocesso).
Uma versão anterior desta tabela listava codex-mcp como um quinto CLI, que nenhum
CliNameSchema validará — CLI_NAMES tem quatro membros, então a configuração
nomeando codex-mcp falha no parsing Zod sem nada no lado da documentação para explicar
o porquê.
Comandos CLI
nexus-agents # Start MCP server (default)
nexus-agents doctor # Check installation health
nexus-agents setup # Configure Claude CLI integration
nexus-agents orchestrate "..." # Run task with experts
nexus-agents vote "proposal" # Multi-agent consensus voting
nexus-agents review <pr-url> # Review a GitHub PR
nexus-agents expert list # List available experts
nexus-agents workflow list # List workflow templates
nexus-agents config init # Generate config file
nexus-agents init --portable # Create workspace-local .nexus-agents/ for sandboxes
nexus-agents init --portable --mcp-config # Also emit .mcp.json wiring Claude Code to it
nexus-agents init --portable --install --mcp-config # …and install the binary into the workspace
nexus-agents fitness-audit # Run fitness score audit
nexus-agents research query # Query research registry
nexus-agents --help # Full command list
Veja docs/ENTRYPOINTS.md para a referência completa do CLI (28+ comandos).
Ferramentas MCP
Ao executar como servidor MCP, as seguintes ferramentas estão disponíveis. Comece com run — o ponto de entrada padrão: dê a ele um objetivo e o MetaOrquestrador escolhe (e, com execute: true, executa) a estratégia certa. As outras ferramentas do pipeline são caminhos avançados de estratégia forçada para fixar uma específica.
| Ferramenta | Descrição |
|---|---|
orchestrate | Orquestração de tarefas com coordenação via Orchestrator |
create_expert | Criar um agente especialista dedicado |
execute_expert | Executar uma tarefa por meio de um especialista previamente criado (por expertId) |
run_workflow | Executar um modelo de fluxo de trabalho linear (use run_graph_workflow para DAGs) |
delegate_to_model | Selecionar o modelo existente mais adequado para uma tarefa (sem alteração no registro) |
list_experts | Inventário de FUNÇÕES de especialistas para create_expert |
list_workflows | Inventário de MODELOS de múltiplas etapas para run_workflow |
consensus_vote | Votação por consenso entre múltiplos modelos sobre propostas |
research_query | Consultar o registro de pesquisa (status, sobreposição, estatísticas, busca) |
research_add | Adicionar um ARTIGO do arXiv ao registro (para fontes que não são artigos, use research_add_source) |
research_add_source | Adicionar uma fonte NÃO-ARTIGO (repositório/ferramenta/blog) — para artigos do arXiv, use research_add |
research_discover | Descobrir artigos/repositórios de fontes externas |
research_analyze | Analisar o registro em busca de lacunas, tendências e cobertura |
research_catalog_review | Revisar referências de pesquisa catalogadas automaticamente |
research_synthesize | Sintetizar o registro em agrupamentos temáticos com temas |
survey_oss_landscape | Busca transitória de projetos OSS (licença, estrelas, último commit) via GitHub |
vendor_publishing_audit | Consultar a infraestrutura de assinatura de um fornecedor (chaves GPG, padrões de URL, formato de assinatura) |
compare_data_feeds | Comparar dois feeds YAML/JSON: cobertura + eixos por campo |
memory_query | Consultar todos os backends de memória |
memory_stats | Painel de estatísticas do sistema de memória |
memory_write | Gravar em backends de memória tipados |
weather_report | Relatório de desempenho de múltiplas CLIs |
issue_triage | Triar issues do GitHub com classificação de confiança |
run_graph_workflow | Executar um fluxo de trabalho DAG com checkpoints por nó + trilha de auditoria (linear → run_workflow) |
execute_spec | Executar pipeline de especificação da fábrica de software com IA |
registry_import | Redigir YAML para uma NOVA entrada de modelo (para selecionar modelos existentes, use delegate_to_model) |
query_trace | Consultar rastros de execução para observabilidade |
query_task_state | Consultar o log estruturado de estado de tarefa por um ID de tarefa |
get_job_result | Ler o resultado de uma despacho em modo assíncrono por jobId (#3042 / #2631) |
list_jobs | Listar jobs em modo assíncrono em todas as ferramentas — descoberta entre sessões (#3046 / #2631) |
cancel_job | Marcar um job em modo assíncrono como cancelado — idempotente (#3042 Estágio 1b) |
ci_health_check | Saúde da infraestrutura de CI — combina status do GitHub + atividade de execuções recentes (#3076) |
verify_audit_chain | Verificar a cadeia de hash de um diretório de log de auditoria do FileAuditStorage |
repo_analyze | Analisar a estrutura de um repositório GitHub |
repo_security_plan | Gerar pipeline de varredura de segurança para um repositório |
extract_symbols | Símbolos AST da API do compilador TypeScript de um ÚNICO arquivo (funções/classes/tipos) |
search_codebase | Busca entre arquivos por NOMES de símbolos declarados (somente declarações, não usos) |
search_usages | Busca estrutural de uso/pontos de chamada para um símbolo via ast-grep (chamadas, chamadas de membro, new, imports, referências) — a lacuna "onde X é usado" que search_codebase não consegue preencher |
run_dev_pipeline | Pipeline completo de desenvolvimento: pesquisa, planejamento, votação, implementação, QA |
run_pipeline | Executar um plugin de pipeline por nome com entrada tipada |
pr_review | Revisão de PR com múltiplos votantes e porta de verificação (experimental) |
supply_chain_tradeoff_panel | Votação de compensação por eixo para decisões de construir-vs-comprar / cadeia de suprimentos |
improvement_review | Loop de observabilidade com limite — expõe sinais de roteamento/dívida técnica/bugs/segurança a partir de dados de resultado+adequação; arquiva issues candidatas |
run_quality_gate | Executar a porta de qualidade de QA (typecheck/lint/testes/build/segurança) em um diretório de projeto; retorna veredito estruturado de aprovação/reprovação + feedback |
suggest_research_tasks | SOMENTE-SUGESTÃO: tarefas candidatas de pipeline a partir de descobertas de research_discover para revisão — não arquiva/executa nada (#1715) |
list_available_models | Sonda todos os transportes de descoberta de modelos (API OpenRouter + CLIs opencode/claude/codex/gemini) e reporta a saúde de cada transporte — valida se os CLIs/APIs estão acessíveis (#3406) |
run | Ponto de entrada padrão — dê um objetivo, o MetaOrchestrator escolhe a estratégia; retorna a decisão de roteamento (execute:false, somente leitura) ou executa inline (execute:true; dev-pipeline+pipeline+research+consensus conectados) (#3548) |
Configuração
Variáveis de Ambiente:
| Variável | Descrição |
|---|---|
ANTHROPIC_API_KEY | Chave da API Claude |
OPENAI_API_KEY | Chave da API OpenAI |
GOOGLE_AI_API_KEY | Chave da API Gemini |
NEXUS_LOG_LEVEL | Nível de log (debug/info/warn/error) |
Gerar arquivo de configuração:
nexus-agents config init # Creates nexus-agents.yaml
Documentação
| Tópico | Link |
|---|---|
| Referência Completa da CLI | docs/ENTRYPOINTS.md |
| Arquitetura | docs/architecture/README.md |
| Contribuição | CONTRIBUTING.md |
| Padrões de Código | CODING_STANDARDS.md |
| Guia de Início Rápido | QUICK_START.md |
Desenvolvimento
git clone https://github.com/nexus-substrate/nexus-agents.git
cd nexus-agents
pnpm install
pnpm build
pnpm test
Requisitos: Node.js 22.x LTS, pnpm 9.x
Contribuição
- Faça um fork do repositório
- Crie um branch de funcionalidade (
git checkout -b feat/amazing-feature) - Faça commits com conventional commits (
feat(scope): add feature) - Abra um Pull Request
Consulte CONTRIBUTING.md para detalhes.
Licença
MIT - Consulte LICENSE
Construído com Claude Code