# 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) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Node.js Version](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen)](https://nodejs.org) [![TypeScript](https://img.shields.io/badge/TypeScript-5.9+-blue)](https://www.typescriptlang.org) [![MCP Protocol](https://img.shields.io/badge/MCP-2025--11--25-purple)](https://modelcontextprotocol.io) [![npm version](https://img.shields.io/npm/v/nexus-agents)](https://www.npmjs.com/package/nexus-agents) --- ## 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](https://github.com/nexus-substrate/nexus-agents/blob/main/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 ```bash # Install the package npm install nexus-agents # Or install globally for CLI usage npm install -g nexus-agents ``` ### CLI Usage Start the MCP server: ```bash # If installed globally nexus-agents # Or with npx npx nexus-agents ``` ### Programmatic Usage ```typescript 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): ```json { "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: ```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 47 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](https://github.com/nexus-substrate/nexus-agents/blob/main/README.md) for the complete tool list. --- ## Architecture ``` nexus-agents/ ├── packages/ │ └── nexus-agents/ # Main package │ ├── src/ │ │ ├── core/ # Shared types, Result, 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](https://github.com/nexus-substrate/nexus-agents/blob/main/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, Errors, Logger) ``` ### Core Interfaces ```typescript // Unified model interaction interface IModelAdapter { complete(request: CompletionRequest): Promise>; stream(request: CompletionRequest): AsyncIterable; countTokens(text: string): Promise; } // Base agent contract interface IAgent { readonly id: string; readonly role: AgentRole; execute(task: Task): Promise>; handleMessage(msg: AgentMessage): Promise>; } // Workflow execution interface IWorkflowEngine { loadTemplate(path: string): Promise>; execute( workflow: WorkflowDefinition, inputs: unknown ): Promise>; } ``` --- ## 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 ```typescript 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 ```typescript 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 ```typescript 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 ```bash # 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 ```bash # 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](https://github.com/nexus-substrate/nexus-agents/blob/main/CODING_STANDARDS.md) for detailed guidelines. See [CONTRIBUTING.md](https://github.com/nexus-substrate/nexus-agents/blob/main/CONTRIBUTING.md) for contribution workflow. ### Commit Convention We use [Conventional Commits](https://www.conventionalcommits.org/): ``` 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](https://github.com/nexus-substrate/nexus-agents/blob/main/LICENSE) for details. --- --- Built with Claude Code