Nexus Agents

# Nexus Agents

[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/12365/badge)](https://www.bestpractices.dev/projects/12365) [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/nexus-substrate/nexus-agents/badge)](https://securityscorecards.dev/viewer/?uri=github.com/nexus-substrate/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)

[![npm version](https://img.shields.io/npm/v/nexus-agents)](https://www.npmjs.com/package/nexus-agents)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen)](https://nodejs.org)
[![Claims Registry Drift](https://img.shields.io/github/actions/workflow/status/nexus-substrate/nexus-agents/docs-check.yml?branch=main&label=claims%20registry)](https://github.com/nexus-substrate/nexus-agents/actions/workflows/docs-check.yml)

---

## 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](https://en.wikipedia.org/wiki/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 |
| Admission control  | gates (`pr_review`, `consensus_vote`, `run_quality_gate`) | 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](docs/adr/0017-authority-ladder.md) (`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                                                        |
| Self-healing     | Routes around failing dependencies automatically | Adapter circuit-breaker + swarm-health demotion (`cli-adapters/circuit-breaker.ts`); a capped, auto-decaying, demotion-only `TuneAdjustmentStore` adjustment |
| Self-optimizing  | Learns where the next task should go             | Closed-loop `Outco

... (truncated)