nexus-agents

Nexus Agents

Governance substrate for your AI coding agents — adversarial review, drift-detected rules, tamper-evident append-only audit chain, human-gated closed-loop tuning (autonomous demotion, earned promotion)

---

Overview

Nexus Agents is a governance layer that sits above your AI coding agents — Claude, Codex, Gemini, and OpenCode. The agents do the engineering; nexus-agents enforces the rules they follow, reviews their work adversarially before it ships, audits everything they touch, and routes the next task based on what actually worked (LinUCB bandit + TOPSIS scoring fed by an outcome store). It connects to any MCP-compatible editor. Routing is a means to the governance end, not the product.

Key Capabilities

• Intelligent Routing — Multi-stage CompositeRouter (TOPSIS, LinUCB bandit, distilled-rule short-circuit, weather-aware penalties). Learns from outcomes.
• Multi-Expert Orchestration — Specialized expert agents (code, architecture, security, testing, docs, devops, research, PM, UX, infrastructure, QA, data-visualization) coordinated by an Orchestrator.
• Consensus Voting — Six aggregation strategies: simple/super-majority, unanimous, higher-order Bayesian, opinion-wise, proof-of-learning.
• Development Pipeline — Research → Plan → Vote → Decompose → Implement → QA → Security. Autonomous, harness, and dry-run modes.
• Memory & Learning — Multiple backends (session, belief, adaptive, routing, graph, hybrid, agentic, typed) with cross-session persistence.
• MCP Tools — Agent management, workflow execution, research, memory, codebase intelligence, repo analysis, consensus, operations. See docs/ENTRYPOINTS.md for the canonical list.
• Research System — Discovery across arXiv, GitHub, Semantic Scholar, and other sources with auto-catalog and synthesis.
• Security — Sandboxing, trust classification, SARIF parsing, input sanitization, red team pipeline.

---

Quick Start

Installation

# Install the package
npm install nexus-agents

# Or install globally for CLI usage
npm install -g nexus-agents

CLI Usage

Start the MCP server:

# If installed globally
nexus-agents

# Or with npx
npx nexus-agents

Programmatic Usage

import { startStdioServer, ExpertFactory, createClaudeAdapter } from 'nexus-agents';

// Start MCP server (recommended — used by Claude Code, Claude Desktop, etc.)
const result = await startStdioServer({
  name: 'my-server',
  version: '1.0.0',
});

// Or use programmatically with model adapters
const adapter = createClaudeAdapter({
  model: 'claude-sonnet-4-6',
});

// Create experts dynamically
const factory = new ExpertFactory(adapter);
const codeExpert = factory.create({ type: 'code' });
const securityExpert = factory.create({ type: 'security' });

Claude Desktop Integration

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "nexus-agents": {
      "command": "npx",
      "args": ["nexus-agents"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

---

Features

Multi-Agent Orchestration

The Orchestrator agent analyzes incoming tasks and delegates to specialized experts:

Expert	Specialization
Code Expert	Implementation, debugging, optimization, refactoring
Architecture Expert	System design, patterns, trade-offs, scalability
Security Expert	Vulnerability analysis, secure coding, threat modeling
Documentation Expert	Technical writing, API docs, code comments
Testing Expert	Test strategies, coverage analysis, test generation
DevOps Expert	CI/CD, deployment, containerization
Research Expert	Literature review, state-of-the-art analysis
PM Expert	Product management, requirements, priorities
UX Expert	User experience, usability, accessibility
Infrastructure Expert	Server management, bare metal, networking
QA Expert	Quality gates, test-plan review, defect triage
Data-Visualization Expert	Charts, diagrams, dashboards, data presentation

All twelve expert types can collaborate on complex tasks. The Orchestrator combines their outputs into a single response.

Model Adapters

Use different AI models through unified interfaces:

Provider	CLI	Best For
Claude	claude	Complex reasoning, analysis
Gemini	gemini	Long context, multimodal
Codex	codex	Code generation, reasoning
OpenCode	opencode	Custom OpenAI-compatible endpoints

Model selection uses composite routing: Budget → Zero-cost → Preference → TOPSIS → LinUCB bandit.

Workflow Engine

Define reusable workflows in YAML:

name: code-review
description: Comprehensive code review workflow
steps:
  - agent: security_expert
    action: scan_vulnerabilities
    output: security_report

  - agent: code_expert
    action: review_quality
    input: ${security_report}
    output: quality_report

  - agent: testing_expert
    action: analyze_coverage
    parallel: true

  - agent: documentation_expert
    action: check_documentation
    parallel: true

MCP Tools

The server exposes 46 MCP tools for integration. Key tools include:

Tool	Description
orchestrate	Analyze task and coordinate expert execution
create_expert	Create a specialized expert agent
execute_expert	Execute a task using a created expert
run_workflow	Execute a workflow template
delegate_to_model	Route task to optimal model
consensus_vote	Multi-model consensus voting on proposals
research_discover	Discover papers/repos from external sources
memory_query	Query across all memory backends
issue_triage	Triage GitHub issues with trust classification
repo_analyze	Analyze GitHub repository structure
repo_security_plan	Generate security scanning pipeline for a repo

See the root README for the complete tool list.

---

Architecture

nexus-agents/
├── packages/
│   └── nexus-agents/         # Main package
│       ├── src/
│       │   ├── core/         # Shared types, Result<T,E>, errors, logger
│       │   ├── config/       # Configuration, model registry, timeouts
│       │   ├── adapters/     # Model adapters (Claude, OpenAI, Gemini, Ollama)
│       │   ├── agents/       # Agent framework (Orchestrator, Experts)
│       │   ├── workflows/    # Workflow engine and YAML templates
│       │   ├── mcp/          # MCP server and tool definitions
│       │   ├── cli-adapters/ # External CLI integration (Claude/Gemini/Codex/OpenCode)
│       │   ├── context/      # Token counting, work balancing
│       │   ├── consensus/    # Multi-agent voting with higher-order aggregation
│       │   ├── memory/       # 8 memory backends (session, belief, adaptive, routing, graph, hybrid, agentic, typed)
│       │   ├── security/     # Input sanitization, trust classification, policy gate
│       │   ├── orchestration/# Graph workflows, AOrchestra, worker dispatch
│       │   ├── pipeline/     # Task contracts, plugin registry, event bus
│       │   ├── index.ts      # Main exports
│       │   └── cli.ts        # CLI entry point
│       └── package.json
├── .claude/
│   ├── rules/                # Claude Code rules
│   └── skills/               # Project-specific skills
└── pnpm-workspace.yaml

See docs/architecture/README.md for detailed module descriptions.

Dependency Flow

MCP Server (external boundary)
    ↓
Orchestration Layer (workflows, graph execution, worker dispatch)
    ↓
Agents Layer (Orchestrator, 12 Expert types)
    ↓
Adapters Layer (Claude, Gemini, Codex, OpenCode CLIs)
    ↓
Core Layer (Types, Result<T,E>, Errors, Logger)

Core Interfaces

// Unified model interaction
interface IModelAdapter {
  complete(request: CompletionRequest): Promise<Result<Response, ModelError>>;
  stream(request: CompletionRequest): AsyncIterable<StreamChunk>;
  countTokens(text: string): Promise<number>;
}

// Base agent contract
interface IAgent {
  readonly id: string;
  readonly role: AgentRole;
  execute(task: Task): Promise<Result<TaskResult, AgentError>>;
  handleMessage(msg: AgentMessage): Promise<Result<AgentResponse, AgentError>>;
}

// Workflow execution
interface IWorkflowEngine {
  loadTemplate(path: string): Promise<Result<WorkflowDefinition, ParseError>>;
  execute(
    workflow: WorkflowDefinition,
    inputs: unknown
  ): Promise<Result<WorkflowResult, WorkflowError>>;
}

---

Configuration

Environment Variables

Variable	Description	Required
ANTHROPIC_API_KEY	Claude API key	Yes (for Claude)
OPENAI_API_KEY	OpenAI API key	For OpenAI models
GOOGLE_AI_API_KEY	Google AI API key	For Gemini models
OLLAMA_HOST	Ollama server URL	For Ollama (default: localhost:11434)
NEXUS_LOG_LEVEL	Log level (debug/info/warn/error)	No

---

API Reference

Adapters

import {
  createClaudeAdapter,
  createOpenAIAdapter,
  createGeminiAdapter,
  createOllamaAdapter,
  AdapterFactory,
} from 'nexus-agents';

// Create individual adapters
const claude = createClaudeAdapter({ model: 'claude-sonnet-4-6' });
const openai = createOpenAIAdapter({ model: 'gpt-4o' });
const gemini = createGeminiAdapter({ model: 'gemini-3-pro' });
const ollama = createOllamaAdapter({ model: 'llama3:8b' });

// Or use the factory
const factory = new AdapterFactory();
const adapter = factory.create({ provider: 'anthropic', model: 'claude-sonnet-4-6' });

Agents

import { ExpertFactory } from 'nexus-agents';

// Create experts for specific domains
const factory = new ExpertFactory(adapter);
const codeExpert = factory.create({ type: 'code' });
const securityExpert = factory.create({ type: 'security' });
const infraExpert = factory.create({ type: 'infrastructure' });

MCP Server

import { createServer, startStdioServer, registerTools } from 'nexus-agents';

// Create and start server
const result = await startStdioServer({
  name: 'my-server',
  version: '1.0.0',
});

if (result.ok) {
  const { server } = result.value;
  // Server is running with stdio transport
}

---

Development

Prerequisites

• Node.js 22.x LTS
• pnpm 9.x
• TypeScript 5.9+

Setup

# Clone the repository
git clone https://github.com/nexus-substrate/nexus-agents.git
cd nexus-agents

# Install dependencies
pnpm install

# Build the package
pnpm build

# Run tests
pnpm test

# Start development mode
pnpm dev

Commands

# Development
pnpm dev              # Start dev server with watch mode
pnpm build            # Build the package
pnpm clean            # Clean build artifacts

# Quality
pnpm lint             # Run ESLint
pnpm lint:fix         # Fix linting issues
pnpm typecheck        # Run TypeScript type checking
pnpm test             # Run all tests
pnpm test:coverage    # Run tests with coverage

---

Contributing

We welcome contributions! Please see our guidelines:

1. Fork the repository
2. Create a feature branch (git checkout -b feat/amazing-feature)
3. Commit with conventional commits (git commit -m 'feat(agents): add amazing feature')
4. Push to your branch (git push origin feat/amazing-feature)
5. Open a Pull Request

Code Standards

• Files must be under 400 lines
• Functions must be under 50 lines
• Coverage thresholds: 60% statements/functions/lines, 50% branches (vitest.config.ts)
• All code must pass linting and type checking

See CODING_STANDARDS.md for detailed guidelines. See CONTRIBUTING.md for contribution workflow.

Commit Convention

We use Conventional Commits:

feat(scope): add new feature
fix(scope): fix bug
refactor(scope): refactor code
docs(scope): update documentation
test(scope): add tests
chore(scope): maintenance tasks

---

License

MIT - See LICENSE for details.

---

---

Built with Claude Code