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 encadeamento hash à 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 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 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 entregue
Log de eventosAuditTrail cadeia hash + verify_audit_chainRegistro somente-acréscimo e à 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 (entregue)
AutoconfigurávelDetecta o ambiente e se integranexus-agents setup / doctor (cli-commands.ts) — detecta CLIs, escreve configuração MCP, reporta saúde
AutocuraRoteia 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
Auto-otimizaçãoAprende para onde a próxima tarefa deve irLoop fechado OutcomeStore → pontuação LinUCB + TOPSIS no CompositeRouter
AutoproteçãoRestringe o que entrada não confiável e ferramentas podem fazerTratamento 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 é enforce mas 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 PRpr_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. 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 desvioCLAUDE.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 AuditTrail com logging estruturado e armazenamento somente-acréscimo com encadeamento hash; a integridade é verificável via a ferramenta MCP verify_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 fechadaOutcomeStore alimenta 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: um signal.swarm_unhealthy (disjuntor de adaptador / saúde do enxame) aplica um pequeno rebaixamento de roteamento limitado e com decaimento automático via TuneAdjustmentStore — somente-rebaixamento, nunca zera um CLI, cada ajuste é auditado, opt-out com NEXUS_TUNE_ENFORCE=false
  • Consenso multi-votanteconsensus_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 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.

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/ (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

CategoriaDetalhes
Revisão Adversarial de PRpr_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 Consenso6 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 DerivaCLAUDE.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 AuditoriaLogging 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 FechadoOutcomeStore 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çaSandboxing (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-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). Auto-catálogo, pontuação de qualidade, síntese em clusters de tópicos
Fluxos de Trabalho em GrafoExecução de fluxo de trabalho baseada em DAG com checkpoint/retomada, redução de estado e hooks de eventos
47 Ferramentas MCPGerenciamento 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

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 aceitação, 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 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
opencodeCompatível com OpenAI personalizadoEndpoints 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.

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 FUNÇÕES 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 agrupamentos temáticos 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 de múltiplas CLIs
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 uma 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_jobMarcar um job em modo assíncrono como cancelado — idempotente (#3042 Estágio 1b)
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 do 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 porta de verificação (experimental)
supply_chain_tradeoff_panelVotação de compensação por eixo para decisões de construir-vs-comprar / cadeia de suprimentos
improvement_reviewLoop 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_gateExecutar 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_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)

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