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)
接入你的智能体
發布者自己的指令。不是 PlugMCP 端點。
用我們的金鑰與日誌託管一份副本。
npx -y [email protected]Claude Code 沒有本機指令的安裝連結。複製下方指令並在終端機中執行。
claude mcp add nexus-agents -- npx -y nexus-agents@15.4.0在終端機中執行。
{ "mcpServers": { "nexus-agents": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}claude_desktop_config.json
遠端 URL 還是本機指令? 兩種安裝方式的差異
來自發布者
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)
Governance substrate for AI coding agents — adversarial PR review, drift-detected rules, tamper-evident audit, and closed-loop outcome routing for Claude, Codex, Gemini, and OpenCode
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.
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 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
enforcebut 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:
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.mdCLAUDE.md + governance:check + blocking CI gates fail the build when documented rules drift from registered behavior (model registry, MCP tools, expert types, skills)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)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=falseconsensus_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-wiseYou: "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:
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.
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.
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.
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.
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.
setup configuresBy 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.
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.
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.
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).
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.
Environment Variables:
Generate config file:
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 24.x LTS, pnpm 9.x
git checkout -b feat/amazing-feature)feat(scope): add feature)See CONTRIBUTING.md for details.
MIT - See LICENSE
Built with Claude Code
Governance substrate for AI coding agents — adversarial PR review, drift-detected rules, tamper-evident audit, and closed-loop outcome routing for Claude, Codex, Gemini, and OpenCode
{ "mcpServers": { "nexus-agents": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式,而不是 PlugMCP 代理伺服器。
這筆記錄未列出必要的環境變數。
Nexus Agents 透過 stdio 在本機執行。
上次檢查時間:2026-11-16。 Governance substrate for AI coding agents — adversarial PR review, drift-detected rules, tamper-evident audit, and closed-loop outcome routing for Claude, Codex, Gemini, and OpenCode