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
2026-11-15
Yıldızlar
—
Araçlar
—
Çalışma süresi
—
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:
Control-plane role
nexus-agents component
What it does
Scheduler
run / MetaOrchestrator
One entry point picks (and optionally runs) the right strategy for a goal
Adversarial review and quality gates decide what is allowed to ship
Event log
AuditTrail hash chain + verify_audit_chain
Append-only, tamper-evident record of every decision
Data plane
engineering CLIs
Claude Code, Codex, Gemini, OpenCode do the file edits, tests, PRs
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):
Self-* property
What it means here
Implementing loop (shipped)
Self-configuring
Detects environment and wires itself in
nexus-agents setup / doctor (cli-commands.ts) — detects CLIs, writes MCP config, reports health
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):
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
Category
Details
Adversarial PR Review
pr_review MCP tool: 5 voter roles (architect, security, devex, catfish, scope_steward) with 4-point gate. v5 evaluation (focused synthetic dataset, n=10): 100% bug-catch, 50% raw FP rate; manual triage reclassified one of two inspected FP cases as a real finding (directional small-n, not measured rates) (details)
CLAUDE.md + inject-governance.ts check enforces single-source registries (model registry, MCP tools, expert types). Blocking CI gate fails build on drift
Audit Trail
Structured logging for every tool call, voter decision, and routing choice. Tamper-evident hash-chained append-only storage (tamper-evident, not tamper-proof — see threat model); integrity verifiable via verify_audit_chain MCP tool
Closed-Loop Telemetry
OutcomeStore feeds LinUCB + TOPSIS scoring; a second bounded, audited self-tuning loop demotes unhealthy CLIs (capped, auto-decaying, on by default, opt-out NEXUS_TUNE_ENFORCE=false)
Nexus-agents routes tasks through 4 CLI adapters, each connecting to major AI providers:
CLI
Provider
Best For
claude
Anthropic (Claude)
Complex reasoning, analysis
gemini
Google (Gemini)
Long context, multimodal
codex
OpenAI (Codex)
Code generation, reasoning
opencode
Custom OpenAI-compat
Custom endpoints, local models
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
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.
Tool
Description
orchestrate
Task orchestration with Orchestrator coordination
create_expert
Create a specialized expert agent
execute_expert
Run a task through a previously-created expert (by expertId)
run_workflow
Run a linear workflow template (use run_graph_workflow for DAGs)
delegate_to_model
Pick the best-fit existing model for a task (no registry change)
list_experts
Inventory of expert ROLES for create_expert
list_workflows
Inventory of multi-step TEMPLATES for run_workflow
consensus_vote
Multi-model consensus voting on proposals
research_query
Query research registry (status, overlap, stats, search)
research_add
Add an arXiv PAPER to the registry (for non-paper sources use research_add_source)
research_add_source
Add a NON-PAPER source (repo/tool/blog) — for arXiv papers use research_add
research_discover
Discover papers/repos from external sources
research_analyze
Analyze registry for gaps, trends, coverage
research_catalog_review
Review auto-cataloged research references
research_synthesize
Synthesize registry into topic clusters with themes
survey_oss_landscape
Transient OSS project search (license, stars, last-commit) via GitHub
vendor_publishing_audit
Look up a vendor's signing infrastructure (GPG keys, URL patterns, signature shape)
compare_data_feeds
Diff two YAML/JSON feeds: coverage + per-field axes
memory_query
Query across all memory backends
memory_stats
Memory system statistics dashboard
memory_write
Write to typed memory backends
weather_report
Multi-CLI performance weather report
issue_triage
Triage GitHub issues with trust classification
run_graph_workflow
Run a DAG workflow with per-node checkpoints + audit trail (linear → run_workflow)
execute_spec
Execute AI software factory spec pipeline
registry_import
Draft YAML for a NEW model entry (for picking existing models use delegate_to_model)
query_trace
Query execution traces for observability
query_task_state
Query the structured task-state log for a task ID
get_job_result
Read result of an async-mode dispatch by jobId (#3042 / #2631)
list_jobs
List async-mode jobs across all tools — cross-session discovery (#3046 / #2631)
cancel_job
Cancel an async-mode job; aborts in-flight voters and workers — idempotent (#3042)
ci_health_check
CI infrastructure health — composes GitHub status + recent-runs activity (#3076)
verify_audit_chain
Verify hash chain of a FileAuditStorage audit log directory
repo_analyze
Analyze GitHub repository structure
repo_security_plan
Generate security scanning pipeline for a repo
extract_symbols
TypeScript-compiler-API AST symbols from a SINGLE file (functions/classes/types)
search_codebase
Cross-file search over declared symbol NAMES (declarations only, not usages)
search_usages
Structural usage/call-site search for a symbol via ast-grep (calls, member calls, new, imports, references) — the "where is X used" gap search_codebase cannot fill
run_dev_pipeline
Full dev pipeline: research, plan, vote, implement, QA
run_pipeline
Execute a pipeline plugin by name with typed input
pr_review
Multi-voter PR review with verification gate (experimental)
supply_chain_tradeoff_panel
Per-axis tradeoff vote for build-vs-buy / supply-chain decisions
Run the QA quality gate (typecheck/lint/tests/build/security) over a project dir; returns structured pass/fail verdict + feedback
suggest_research_tasks
SUGGEST-ONLY: candidate pipeline tasks from research_discover findings for review — files/executes nothing (#1715)
list_available_models
Probe all model-discovery transports (OpenRouter API + opencode/claude/codex/gemini CLIs) and report per-transport health — validates the CLIs/APIs are reachable (#3406)
run
Default entry point — give a goal, MetaOrchestrator picks the strategy; returns the routing decision (execute:false, read-only) or runs it inline (execute:true; dev-pipeline+pipeline+research+consensus wired) (#3548)
Configuration
Environment Variables:
Variable
Description
ANTHROPIC_API_KEY
Claude API key
OPENAI_API_KEY
OpenAI API key
GOOGLE_AI_API_KEY
Gemini API key
NEXUS_LOG_LEVEL
Log level (debug/info/warn/error)
NEXUS_DISABLED_CLIS
Comma-separated CLIs to take out of service (e.g. codex,gemini). Disables the CLI transport only: the binary is never spawned. On a gateway host the family's gateway model still serves the slot (#6723)
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
Henüz araç listesi yok. Uzak sunucular ilk sağlık kontrolünden sonra bir liste alır.
SSS
Sorular
Nexus Agents nasıl kurulur?
Bu sayfadan Cursor, Claude Desktop, Claude Code veya VS Code için stdio yapılandırmasını kopyalayın. PlugMCP proxy'sini değil, yayıncının kurulumunu kullanır.
Nexus Agents için API anahtarı gerekiyor mu?
Bu kayıtta gerekli bir ortam değişkeni listelenmiyor.
Nexus Agents hangi aktarımı kullanıyor?
Nexus Agents yerel olarak stdio üzerinden çalışır.
Nexus Agents en son ne zaman kontrol edildi?
Son kontrol: 2026-11-15. 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
