Nexus Agents

The intelligence layer between you and your AI coding tools

---

Overview

Nexus Agents makes your AI coding tools work together intelligently. It coordinates Claude, Codex, Gemini, and OpenCode — routing each task to the best model using data-driven algorithms (LinUCB bandit, TOPSIS scoring, adaptive bonuses), validating outputs through multi-model consensus voting, and continuously improving through outcome-driven learning. Connect it to any MCP-compatible editor and it handles the rest.

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
Copy

CLI Usage

Start the MCP server:

# If installed globally
nexus-agents

# Or with npx
npx nexus-agents
Copy

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' });
Copy

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-..."
      }
    }
  }
}
Copy

---

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

Experts 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
Copy

MCP Tools

The server exposes 24 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
Copy

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, 10 Expert types)
    ↓
Adapters Layer (Claude, Gemini, Codex, OpenCode CLIs)
    ↓
Core Layer (Types, Result<T,E>, Errors, Logger)
Copy

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>>;
}
Copy

---

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-1.5-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' });
Copy

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' });
Copy

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
}
Copy

---

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
Copy

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
Copy

---

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
• Test coverage must be at least 80%
• 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
Copy

---

License

MIT - See LICENSE for details.

---

---

Built with Claude Code