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

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 |

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

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

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)

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

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/williamzujkowski/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
• 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

License

MIT - See LICENSE for details.

Built with Claude Code