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

OpenSSF Best Practices OpenSSF Scorecard

Plano de controle autonômico para agentes de codificação de IA — um único ponto de entrada, revisão adversarial, auditoria com hash encadeado à prova de adulteração, ajuste de malha fechada com gate humano (rebaixamento autônomo, promoção conquistada)

npm version License: MIT Node.js Version Claims Registry Drift


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 enviado, 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 permitem, autogerenciado em vez de conduzido manualmente.

O mapeamento do plano de controle

Cada papel clássico do plano de controle mapeia para um componente enviado do nexus-agents — a metáfora é estrutural, não decorativa:

Papel no plano de controleComponente nexus-agentsO que faz
Agendadorrun / MetaOrchestratorUm único ponto de entrada escolhe (e opcionalmente executa) a estratégia certa para um objetivo
Controle de admissãogates (pr_review, consensus_vote, run_quality_gate)Revisão adversarial e gates de qualidade decidem o que pode ser enviado
Log de eventosAuditTrail cadeia de hash + verify_audit_chainRegistro somente de acréscimo, à prova de adulteração, de cada decisão
Plano de dadosCLIs de engenhariaClaude 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 aquiLoop implementado (enviado)
Self-configuringDetecta o ambiente e se integra automaticamentenexus-agents setup / doctor (cli-commands.ts) — detecta CLIs, escreve configuração MCP, reporta saúde
Self-healingRoteia ao redor de dependências com falha automaticamenteDisjuntor de adaptador + rebaixamento por saúde do enxame (cli-adapters/circuit-breaker.ts); um ajuste TuneAdjustmentStore limitado, com decaimento automático e somente rebaixamento
Self-optimizingAprende para onde a próxima tarefa deve irLoop fechado OutcomeStore → pontuação LinUCB + TOPSIS no CompositeRouter
Self-protectingRestringe o que entrada não confiável e ferramentas podem fazerTratamento de entrada por níveis de confiança, denylist de caminhos secretos do PolicyFirewall (secret-paths), sandboxing Docker/política (security/)

Nota de honestidade: esses loops estão em degraus diferentes da escada de autoridade. O rebaixamento por autoajuste é enforce mas limitado (com teto, 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_review executa 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. Estes 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 deriva — CLAUDE.md + governance:check + gates de CI bloqueantes falham o build quando regras documentadas divergem 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 AuditTrail com logging estruturado e armazenamento somente de acréscimo com cadeia de hash; a integridade é verificável via a ferramenta MCP verify_audit_chain (à prova de adulteração, não inviolável — veja o modelo de ameaça da cadeia de hash de auditoria)
  • Roteamento de malha fechada — OutcomeStore alimenta a telemetria de produção de volta na pontuação LinUCB + TOPSIS para que o sistema realmente aprenda com o que foi enviado versus o que regrediu. Um segundo loop, limitado, executa por padrão: um signal.swarm_unhealthy (disjuntor de adaptador / saúde do enxame) aplica um pequeno rebaixamento de roteamento com teto e decaimento automático via TuneAdjustmentStore — somente rebaixamento, nunca zera um CLI, cada ajuste é auditado, opt-out com NEXUS_TUNE_ENFORCE=false
  • Consenso multi-votante — consensus_vote executa um painel padrão de 7 papéis (arquiteto, segurança, devex, ai_ml, pm, catfish, scope_steward; --quick usa 3). Seis nomes de estratégia (cinco distintos: higher_order é um alias de opinion_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 ajustem; 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 ferramentas 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 autogerenciado dentro de limites, não supervisionado. A autoridade de cada loop é limitada pela escada de autoridade (ADR-0017); promoções para autoridade superior 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 enviado, regras divergindo 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. Instalação

npm install -g nexus-agents

Ou como plugin do Claude Code (instalação com um único 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. Verificação

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 para executar a qualquer momento.

Um CLI desligado com NEXUS_DISABLED_CLIS é listado como desabilitado e não é sondado. Em um host gateway, doctor também informa se o gateway atende o slot daquele CLI (doctor --gateway imprime uma linha por slot); veja CORPORATE_GATEWAY.md.

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: 300s 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 itens no seu ambiente. Cada um pode ser ignorado com a flag --skip-* correspondente se você não quiser.

ConfiguradoOnde é escritoFlag 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/ (session-start / pre-tool / 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

Por padrão, o setup aplica cada etapa sem solicitar. Passe --interactive para executar o assistente de configuração. Quando stdout não é um TTY, ou em CI, passe --non-interactive; sem ele, o setup sai com um erro.

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

CategoriaDetalhes
Revisão Adversarial de PRpr_review Ferramenta MCP: 5 papéis de votação (arquiteto, segurança, devex, catfish, scope_steward) 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 FP; triagem manual reclassificou um dos dois casos de FP inspecionados como um achado real (direcional pequeno-n, não taxas medidas) (detalhes)
Votação por Consenso6 estratégias: simple_majority, supermajority, unanimous, higher_order (Bayesiano ciente de correlação), opinion_wise, proof_of_learning
Charter com Detecção de DriftCLAUDE.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 drift
Trilha de AuditoriaLogging estruturado para cada chamada de ferramenta, decisão de votação e escolha de roteamento. Armazenamento append-only com hash encadeado à 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 Loop FechadoOutcomeStore alimenta 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, opt-out NEXUS_TUNE_ENFORCE=false)
Pipeline de SegurançaSandboxing (Docker/política), tratamento de entrada por níveis de confiança, parsing SARIF, padrões de red-team, denylist de caminhos secretos do PolicyFirewall (secret-paths)
Orquestração Multi-Especialista12 tipos de especialistas integrados coordenados pelo Orquestrador. Papéis vinculam prompt + ferramentas + memória
Pipeline de DesenvolvimentoPesquisa → Plano → Voto → Decomposição → Implementação → QA → Segurança. Três modos: autônomo, harness (chamador implementa), dry-run
Memória e Aprendizado5 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 Pesquisa9 fontes de descoberta (arXiv, GitHub, Semantic Scholar, etc). Catálogo automático, pontuação de qualidade, síntese em clusters de tópicos
Fluxos de Trabalho em GrafoExecução de fluxos de trabalho baseada em DAG com checkpoint/retomada, redução de estado e hooks de eventos
47 Ferramentas MCPGerenciamento de agentes, execução de fluxos de trabalho, pesquisa, memória, inteligência de código, análise de repositório, consenso, operações

Especialistas Disponíveis

EspecialistaEspecialização
CódigoImplementação, depuração, otimização
ArquiteturaDesign de sistemas, padrões, escalabilidade
SegurançaAnálise de vulnerabilidades, codificação segura
TestesEstratégias de teste, cobertura, geração de testes
QACritérios de aceite, verificações de regressão
DocumentaçãoEscrita técnica, docs de API
DevOpsCI/CD, implantação, infraestrutura
PesquisaRevisão de literatura, análise de estado da arte
PMGestão de produto, requisitos, prioridades
UXExperiência do usuário, usabilidade, acessibilidade
InfraestruturaGerenciamento de servidores, bare metal, redes
Visualização de DadosGráficos, dashboards, apresentação visual de dados

CLIs e Provedores Suportados

Nexus-agents roteia tarefas por 4 adaptadores de CLI, cada um conectando-se aos principais provedores de IA:

CLIProvedorMelhor Para
claudeAnthropic (Claude)Raciocínio complexo, análise
geminiGoogle (Gemini)Contexto longo, multimodal
codexOpenAI (Codex)Geração de código, raciocínio
opencodeCustom OpenAI-compatEndpoints 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 -p "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 da 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 MetaOrchestrator escolhe (e, com execute: true, executa) a estratégia certa. As outras ferramentas de pipeline são caminhos avançados de força de estratégia para fixar uma específica.

FerramentaDescrição
orchestrateOrquestração de tarefas com coordenação via Orchestrator
create_expertCriar um agente especialista dedicado
execute_expertExecutar uma tarefa por meio de um especialista previamente criado (por expertId)
run_workflowExecutar um modelo de fluxo de trabalho linear (use run_graph_workflow para DAGs)
delegate_to_modelSelecionar o modelo existente mais adequado para uma tarefa (sem alteração no registro)
list_expertsInventário de PAPÉIS de especialistas para create_expert
list_workflowsInventário de MODELOS de múltiplas etapas para run_workflow
consensus_voteVotação por consenso entre múltiplos modelos sobre propostas
research_queryConsultar o registro de pesquisa (status, sobreposição, estatísticas, busca)
research_addAdicionar um ARTIGO do arXiv ao registro (para fontes que não são artigos, use research_add_source)
research_add_sourceAdicionar uma fonte NÃO-ARTIGO (repositório/ferramenta/blog) — para artigos do arXiv use research_add
research_discoverDescobrir artigos/repositórios de fontes externas
research_analyzeAnalisar o registro em busca de lacunas, tendências e cobertura
research_catalog_reviewRevisar referências de pesquisa catalogadas automaticamente
research_synthesizeSintetizar o registro em clusters de tópicos com temas
survey_oss_landscapeBusca transitória de projetos OSS (licença, estrelas, último commit) via GitHub
vendor_publishing_auditConsultar a infraestrutura de assinatura de um fornecedor (chaves GPG, padrões de URL, formato de assinatura)
compare_data_feedsComparar dois feeds YAML/JSON: cobertura + eixos por campo
memory_queryConsultar todos os backends de memória
memory_statsPainel de estatísticas do sistema de memória
memory_writeGravar em backends de memória tipados
weather_reportRelatório de desempenho multi-CLI
issue_triageTriar issues do GitHub com classificação de confiança
run_graph_workflowExecutar um fluxo de trabalho DAG com checkpoints por nó + trilha de auditoria (linear → run_workflow)
execute_specExecutar pipeline de especificação da fábrica de software com IA
registry_importRedigir YAML para uma NOVA entrada de modelo (para selecionar modelos existentes use delegate_to_model)
query_traceConsultar rastros de execução para observabilidade
query_task_stateConsultar o log estruturado de estado de tarefa por um ID de tarefa
get_job_resultLer o resultado de um despacho em modo assíncrono por jobId (#3042 / #2631)
list_jobsListar jobs em modo assíncrono em todas as ferramentas — descoberta entre sessões (#3046 / #2631)
cancel_jobCancelar um job em modo assíncrono; aborta votantes e trabalhadores em andamento — idempotente (#3042)
ci_health_checkSaúde da infraestrutura de CI — combina status do GitHub + atividade de execuções recentes (#3076)
verify_audit_chainVerificar a cadeia de hash de um diretório de log de auditoria FileAuditStorage
repo_analyzeAnalisar a estrutura de um repositório GitHub
repo_security_planGerar pipeline de varredura de segurança para um repositório
extract_symbolsSímbolos AST da API do compilador TypeScript de um ÚNICO arquivo (funções/classes/tipos)
search_codebaseBusca entre arquivos por NOMES de símbolos declarados (somente declarações, não usos)
search_usagesBusca 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_pipelinePipeline completo de desenvolvimento: pesquisa, planejamento, votação, implementação, QA
run_pipelineExecutar um plugin de pipeline por nome com entrada tipada
pr_reviewRevisão de PR com múltiplos votantes e gate de verificação (experimental)
supply_chain_tradeoff_panelVotação de tradeoff por eixo para decisões de construir-vs-comprar / cadeia de suprimentos
improvement_reviewLoop de observabilidade com gate por limiar — expõe sinais de roteamento/dívida técnica/bugs/segurança a partir de dados de resultado+aptidão; arquiva issues candidatas
run_quality_gateExecutar o gate 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_tasksSOMENTE-SUGESTÃO: tarefas candidatas de pipeline a partir de descobertas de research_discover para revisão — não arquiva/executa nada (#1715)
list_available_modelsSonda 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)
runPonto 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ávelDescrição
ANTHROPIC_API_KEYChave da API Claude
OPENAI_API_KEYChave da API OpenAI
GOOGLE_AI_API_KEYChave da API Gemini
NEXUS_LOG_LEVELNível de log (debug/info/warn/error)
NEXUS_DISABLED_CLISCLIs separados por vírgula para colocar fora de serviço (ex.: codex,gemini). Desativa apenas o transporte CLI: o binário nunca é iniciado. Em um host gateway, o modelo gateway da família ainda atende ao slot (#6723)

Gerar arquivo de configuração:

nexus-agents config init   # Creates nexus-agents.yaml

Documentação

TópicoLink
Referência Completa da CLIdocs/ENTRYPOINTS.md
Arquiteturadocs/architecture/README.md
ContribuiçãoCONTRIBUTING.md
Padrões de CódigoCODING_STANDARDS.md
Guia de Início RápidoQUICK_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

  1. Faça um fork do repositório
  2. Crie um branch de funcionalidade (git checkout -b feat/amazing-feature)
  3. Faça commits com conventional commits (feat(scope): add feature)
  4. Abra um Pull Request

Consulte CONTRIBUTING.md para detalhes.


Licença

MIT - Consulte LICENSE


Construído com Claude Code