Nexus Agents

Multi-agent orchestration MCP server with model diversity and workflow automation

Overview

Nexus Agents is an MCP (Model Context Protocol) server that coordinates multiple AI experts to handle software development tasks. It provides a unified interface for different AI models and enables multi-agent collaboration through an Orchestrator and 10 specialized experts.

Key Capabilities

• Multi-Agent Orchestration - Orchestrator coordinates 10 specialized experts for complex tasks
• Model Diversity - Support for Claude, Gemini, Codex, and OpenCode (with custom OpenAI-compatible endpoints)
• Workflow Automation - 11 YAML-based templates for repeatable processes
• Consensus Voting - Multi-agent voting with higher-order Bayesian aggregation
• Memory System - 5 typed backends (session, belief, agentic, adaptive, typed)
• 24 MCP Tools - Full integration with Claude Code, Claude Desktop, and other MCP clients
• Security-First Design - Defense in depth with input validation and untrusted input hardening

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/       # 5 typed memory backends (session, belief, agentic, adaptive, 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