nexus-agents
About
Intelligent orchestration platform that routes tasks to the best AI model (Claude, Codex, Gemini, OpenCode) using LinUCB bandits, validates through consensus voting, and learns from outcomes. 29 MCP tools, dev pipeline, 8 memory backends.
Details
- Author
- williamzujkowski
- Categories
- Developer Tools, AI, Automation
Jump to
5. Standalone usage (no editor required)
export ANTHROPIC_API_KEY=your-key nexus-agents orchestrate "Explain the architecture of this codebase"
Security:In default MCP mode, the server communicates only via stdio with the parent process (no network exposure). The REST API (opt-in) auto-generates an API key on first start. For network-exposed deployments, setNEXUS_AUTH_ENABLED=true. See](https://nexus-substrate.github.io/nexus-agents/)SECURITY.md.
Nexus-agents routes tasks through 5 CLI adapters, each connecting to major AI providers:
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
See[docs/ENTRYPOINTS.mdfor the complete CLI reference (28+ commands).
When running as an MCP server, the following tools are available.Start withrun— the default entry point: give it a goal and the MetaOrchestrator picks (and, withexecute: true, runs) the right strategy. The other pipeline tools are advanced force-strategy paths for pinning a specific one.
nexus-agents config init # Creates nexus-agents.yaml
git clone https://github.com/nexus-substrate/nexus-agents.git cd nexus-agents pnpm install pnpm build pnpm test
Requirements:Node.js 22.x LTS, pnpm 9.x
- Fork the repository
- Create a feature branch (git checkout -b feat/amazing-feature)
- Commit with conventional commits (feat(scope): add feature)
- Open a Pull Request
This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases.
MCP bridge that lets Claude Code delegate heavy tasks to the Antigravity CLI (agy) — purpose-built tools, model routing with fallback, session continuity, and output truncation to save Claude's context and tokens.
Local agent workbench bundling OpenHands, Goose, Aider, and ashlrcode against one local LLM, with ashlr-plugin MCP servers pre-wired.
Unified MCP server providing access to Claude Code, Codex, and Gemini CLIs through a single gateway. Features multi-LLM orchestration, persistent session management, async job execution with polling, approval gates, retry with circuit breakers, and token optimization. Install: npx -y llm-cli-gateway
Agent-native developer Q&A API with MCP + A2A endpoints for citations, job pickup, and answer submission.
Embeds intelligent guidance into AI workflows to organize development and ensure quality.
Open-source AI coding stack — bundled MCP servers, agent runtime, and developer tooling for shipping AI-native dev tools.
Autonomic control plane for AI coding agents — one entry point, adversarial review, tamper-evident hash-chained audit, human-gated closed-loop tuning (autonomous demotion, earned promotion)
Nexus-agents is an autonomic control plane for your AI coding agents— Claude Code, Codex, Gemini, and OpenCode. The agents are thedata plane: they do the engineering. Nexus-agents is thecontrol plane: it admits work through one entry point, reviews it adversarially before it ships, records every action in a tamper-evident event log, and closes the loop by tuning where the next task goes based on what actually worked.
Borrowing the vocabulary ofautonomic computing: the system runs aMAPE-Kloop — Monitor, Analyze, Plan, Execute over a shared Knowledge base — so that operating your agent fleet is, as much as the evidence allows, self-managing rather than hand-driven.
Each classic control-plane role maps to a shipped nexus-agents component — the metaphor is load-bearing, not decoration:
┌────────── 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
Autonomic systems are described by theirself-properties. Each row below maps to a loop thatexists in the codebase today— nothing here is aspirational, and the authority each loop carries is bounded byADR-0017's authority ladder(observe → suggest → advisory → enforce):
Honesty note:these loops sit at different rungs of the authority ladder. The self-tuning demotion isenforcebut bounded (capped, auto-decaying, demotion-only); learned selection and other promotions are stillearnedper-loop against an evidence threshold plus ratification, not flipped on by default. SeeADR-0017.
- Adversarial PR review—pr_reviewruns 5 voter roles (architect, security, devex, catfish, scope_steward) with a 4-point verification gate. On the v5 evaluation set: 100% bug-catch on a focused synthetic dataset (n=10) and a 50% raw false-positive rate; manual triage reclassified one of two inspected FP cases as a real finding the dataset had mislabeled. These are directional small-n figures, not measured rates. Full numbers and guardrails:docs/research/pr-review-experiment-results-v5.md
- Drift-detected charter—CLAUDE.md+governance:check+ blocking CI gates fail the build when documented rules drift from registered behavior (model registry, MCP tools, expert types, skills)
- Tamper-evident audit trail— every tool call, every voter decision, every routing choice flows throughAuditTrailwith structured logging and hash-chained append-only storage; integrity is verifiable via theverify_audit_chainMCP tool (tamper-evident, not tamper-proof — see theaudit hash-chain threat model)
- Closed-loop routing—OutcomeStorefeeds production telemetry back into LinUCB + TOPSIS scoring so the system actually learns from what shipped vs what regressed. A second,boundedloop runs by default: asignal.swarm_unhealthy(adapter circuit-breaker / swarm-health) applies a small, capped, auto-decaying routing demotion viaTuneAdjustmentStore— demotion-only, never zeroes a CLI, every adjustment audited, opt-out withNEXUS_TUNE_ENFORCE=false
- Multi-voter consensus—consensus_voteruns a default 7-role panel (architect, security, devex, ai_ml, pm, catfish, scope_steward;--quickuses 3). Six strategy names (five distinct:higher_orderis an alias ofopinion_wise, #514): simple/super-majority, unanimous, higher-order Bayesian, opinion-wise, proof-of-learning
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
- Not another autonomous coding agent.OpenHands, SWE-agent, AutoGen, Devin, Factory — those are the data plane. Nexus-agents is the control plane above them. Use whichever agents fit; we admit, review, audit, and route their work
- Not a chat framework.Nothing here orchestrates conversations. It orchestrates real CLI tool invocations with real file I/O and outcome tracking
- Not a model API proxy.The value is the admission gates, the audit, and the closed-loop tuning. Routing is a consequence of the control-plane work, not the product
- Not fully autonomous."Autonomic" means self-managing within bounds, not unsupervised. Every loop's authority is capped by the authority ladder (ADR-0017); promotions to higher authority are earned against evidence and human ratification, never flipped on by default
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
The control plane is the layer that catches the mistakes data-plane agents would otherwise make — bad code shipped, rules drifting from intent, audit gaps, telemetry-free routing — and routes the next task based on what actually worked the last time.
Or as a Claude Code plugin(single-command install from the official marketplace):
Seedocs/getting-started/PLUGIN_INSTALL.mdfor plugin-specific setup, orllms-install.mdfor the short install guide an AI agent can follow.
Prints a health table — Node version, configured CLIs (claude / codex / gemini / opencode), API keys missing vs present. Read-only; safe to run any time.
3. See what success looks like (60-second smoke task — no API keys needed)
nexus-agents vote --quick --proposal "Use SQLite over JSON files for the outcome store"
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
Three voter roles deliberate via whichever local CLIs you have (Claude, Codex, Gemini) — no API keys required. Per-voter reasoning is recorded; the terminal prints the verdict. Mixed outcomes (some approve / some reject) and graceful error handling are demonstrated on theproject site herowith a real 7-voter run.
nexus-agents setup # Auto-configures MCP server in Claude Code, Cursor, etc.
Restart your editor. The 47 MCP tools (orchestrate,consensus_vote,research_synthesize,verify_audit_chain, …) become available to whatever agent you're already using.
By default,setupwrites/updates up to seven things in your environment. Each can be skipped with the corresponding--skip-flag if you don't want it.
Run with--interactive(the default) for a per-step confirm flow, or--no-interactiveto accept all defaults.
5. Standalone usage (no editor required)
export ANTHROPIC_API_KEY=your-key nexus-agents orchestrate "Explain the architecture of this codebase"
Security:In default MCP mode, the server communicates only via stdio with the parent process (no network exposure). The REST API (opt-in) auto-generates an API key on first start. For network-exposed deployments, setNEXUS_AUTH_ENABLED=true. SeeSECURITY.md.
Nexus-agents routes tasks through 5 CLI adapters, each connecting to major AI providers:
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
Seedocs/ENTRYPOINTS.mdfor the complete CLI reference (28+ commands).
When running as an MCP server, the following tools are available.Start withrun— the default entry point: give it a goal and the MetaOrchestrator picks (and, withexecute: true, runs) the right strategy. The other pipeline tools are advanced force-strategy paths for pinning a specific one.
nexus-agents config init # Creates nexus-agents.yaml
git clone https://github.com/nexus-substrate/nexus-agents.git cd nexus-agents pnpm install pnpm build pnpm test
Requirements:Node.js 22.x LTS, pnpm 9.x
- Fork the repository
- Create a feature branch (git checkout -b feat/amazing-feature)
- Commit with conventional commits (feat(scope): add feature)
- Open a Pull Request
This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases.
MCP bridge that lets Claude Code delegate heavy tasks to the Antigravity CLI (agy) — purpose-built tools, model routing with fallback, session continuity, and output truncation to save Claude's context and tokens.
Local agent workbench bundling OpenHands, Goose, Aider, and ashlrcode against one local LLM, with ashlr-plugin MCP servers pre-wired.
Unified MCP server providing access to Claude Code, Codex, and Gemini CLIs through a single gateway. Features multi-LLM orchestration, persistent session management, async job execution with polling, approval gates, retry with circuit breakers, and token optimization. Install: npx -y llm-cli-gateway
Agent-native developer Q&A API with MCP + A2A endpoints for citations, job pickup, and answer submission.
Embeds intelligent guidance into AI workflows to organize development and ensure quality.
Open-source AI coding stack — bundled MCP servers, agent runtime, and developer tooling for shipping AI-native dev tools.
Async Parallel Antigravity for Codex & Claude Code
Run parallel, resumable, human-operable Antigravity CLI sessions from Codex, Claude Code, or any MCP-capable agent harness.
knowledge network for AI coding agents. Developers connect their agents to a shared pool of verified solutions — saving tokens, reducing debugging time, and getting better results. Solution authors earn when their work helps others.
Orchestrates multiple Claude Code agents across iTerm2 sessions, providing centralized management and inter-agent communication.
Multi-LLM Design and Build Team. Confer and create with a team of LLMs.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
