Nexus Agents

Nexus Agents

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)

Why Nexus Agents?

Nexus-agents is an autonomic control plane for your AI coding agents — Claude Code, Codex, Gemini, and OpenCode. The agents are the data plane: they do the engineering. Nexus-agents is the control 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 of autonomic computing: the system runs a MAPE-K loop — 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.

The control-plane mapping

Each classic control-plane role maps to a shipped nexus-agents component — the metaphor is load-bearing, not decoration:

The MAPE-K loop

   ┌────────── 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

Self-* capabilities

Autonomic systems are described by their self-* properties. Each row below maps to a loop that exists in the codebase today — nothing here is aspirational, and the authority each loop carries is bounded by ADR-0017's authority ladder (observe → suggest → advisory → enforce):

Honesty note: these loops sit at different rungs of the authority ladder. The self-tuning demotion is enforce but bounded (capped, auto-decaying, demotion-only); learned selection and other promotions are still earned per-loop against an evidence threshold plus ratification, not flipped on by default. See ADR-0017.

What it gives you:

• Adversarial PR review — pr_review runs 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 through AuditTrail with structured logging and hash-chained append-only storage; integrity is verifiable via the verify_audit_chain MCP tool (tamper-evident, not tamper-proof — see the audit hash-chain threat model)
• Closed-loop routing — OutcomeStore feeds production telemetry back into LinUCB + TOPSIS scoring so the system actually learns from what shipped vs what regressed. A second, bounded loop runs by default: a signal.swarm_unhealthy (adapter circuit-breaker / swarm-health) applies a small, capped, auto-decaying routing demotion via TuneAdjustmentStore — demotion-only, never zeroes a CLI, every adjustment audited, opt-out with NEXUS_TUNE_ENFORCE=false
• Multi-voter consensus — consensus_vote runs a default 7-role panel (architect, security, devex, ai_ml, pm, catfish, scope_steward; --quick uses 3). Five strategy names (four distinct: higher_order is an alias of opinion_wise, #514): simple/super-majority, unanimous, higher-order Bayesian, opinion-wise

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

What this is NOT:

• 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

Where nexus-agents sits in your 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

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.

Quick Start (2 minutes)

1. Install

npm install -g nexus-agents

Or as a Claude Code plugin (add the self-hosted marketplace, then install):

/plugin marketplace add nexus-substrate/nexus-agents
/plugin install nexus-agents@nexus-substrate

See docs/getting-started/PLUGIN_INSTALL.md for plugin-specific setup, or llms-install.md for the short install guide an AI agent can follow.

2. Verify

nexus-agents doctor

Prints a health table — Node version, configured CLIs (claude / codex / gemini / opencode), API keys missing vs present. Read-only; safe to run any time.

A CLI switched off with NEXUS_DISABLED_CLIS is listed as disabled and not probed. On a gateway host, doctor also says whether the gateway serves that CLI's slot (doctor --gateway prints one line per slot); see CORPORATE_GATEWAY.md.

For a walkthrough before configuring CLI authentication, run:

nexus-agents tour

The tour shows illustrative cached fixtures, with no live model calls, API keys, or authenticated CLI required. Add --non-interactive to skip the prompts between steps.

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"

You should see:

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

Three voter roles deliberate through authenticated Claude Code or Codex CLIs; at least one must be available. Gemini and OpenCode do not serve voter seats. No separate API keys are required. Per-voter reasoning is recorded; the terminal prints the verdict. Mixed outcomes (some approve / some reject) and graceful error handling are demonstrated on the project site hero with a real 7-voter run.

4. Wire into your editor

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.

What setup configures

By default, setup writes/updates up to six things in your environment. Each can be skipped with the corresponding --skip-* flag if you don't want it.

By default setup applies every step without prompting. Pass --interactive to run the setup wizard instead. Where stdout is not a TTY, or in CI, pass --non-interactive; without it setup exits with an error.

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, set NEXUS_AUTH_ENABLED=true. See SECURITY.md.

Capabilities

Available Experts

Supported CLIs & Providers

Nexus-agents routes tasks through 4 CLI adapters, each connecting to major AI providers:

codex has two transports, selected by configuration rather than by name: CodexMcpAdapter (the default, MCP-native) and CodexCliAdapter (subprocess). An earlier version of this table listed codex-mcp as a fifth CLI, which no CliNameSchema will validate — CLI_NAMES has four members, so configuration naming codex-mcp fails Zod parsing with nothing on the docs side to explain why.

CLI Commands

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

See docs/ENTRYPOINTS.md for the complete CLI reference (28+ commands).

MCP Tools

When running as an MCP server, the following tools are available. Start with run — the default entry point: give it a goal and the MetaOrchestrator picks (and, with execute: true, runs) the right strategy. The other pipeline tools are advanced force-strategy paths for pinning a specific one.

Configuration

Environment Variables:

Generate config file:

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

Documentation

Development

git clone https://github.com/nexus-substrate/nexus-agents.git
cd nexus-agents
pnpm install
pnpm build
pnpm test

Requirements: Node.js 24.x LTS, pnpm 9.x

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feat/amazing-feature)
3. Commit with conventional commits (feat(scope): add feature)
4. Open a Pull Request

See CONTRIBUTING.md for details.

License

MIT - See LICENSE

Built with Claude Code