# nexus-agents - v2.80.0

# 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/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
- 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