Nexus-Agents Entrypoints

Last Updated: 2026-03-01 (ET) Canonical Source: This document is the single source of truth for all entrypoints. Issue: #210 (Epic #209)

Overview

Nexus-agents provides four interface categories:

Quick Reference

Most commonly used commands:

CLI Commands

Entry Point: nexus-agents [command] [options]

Mode Selection

Global Options

Options available for all commands:

Command Options Reference

orchestrate

vote

review

setup

routing-audit

system-review

learning-metrics

research

index

Usage Examples

# Start MCP server (default)
nexus-agents

# Health check
nexus-agents doctor

# Generate config
nexus-agents config init

# List experts
nexus-agents expert list

# Run workflow
nexus-agents workflow run code-review --input='{"url": "..."}'

# Review PR
nexus-agents review https://github.com/owner/repo/pull/123

# Debug routing
nexus-agents routing-audit "Implement a sorting algorithm" --format=json

# Standalone orchestration
nexus-agents orchestrate "Review this code for security issues"

# Consensus voting
nexus-agents vote --proposal "Should we adopt TypeScript 6.0?"

# System review (5-phase checklist)
nexus-agents system-review
nexus-agents system-review --create-issue
nexus-agents system-review --fix --verbose

# Research registry
nexus-agents research status                       # Show all techniques
nexus-agents research status --status=implemented  # Filter by status
nexus-agents research status aegean-consensus      # Show specific technique
nexus-agents research overlap trinity-roles        # Find related techniques
nexus-agents research add 2501.06322 --dry-run     # Preview adding paper
nexus-agents research discover --topic=orchestration                # Discover from all sources
nexus-agents research discover --topic=agents --source=github       # GitHub repos only
nexus-agents research discover --topic=agents --source=semantic_scholar  # Semantic Scholar
nexus-agents research discover --topic=agents --source=papers_with_code  # Papers with Code
nexus-agents research review --topic=orchestration                  # Discover, score, rank findings
nexus-agents research review --topic=agents --create-issues         # Auto-create GitHub issues
nexus-agents research prioritize                                    # Show priority backlog
nexus-agents research prioritize --topic=consensus                  # Filter by topic

# Quick verification
nexus-agents verify

# PR review demo with wizard
nexus-agents review-demo

# Validation dashboard
nexus-agents validation-dashboard

# SWE-bench evaluation
nexus-agents swe-bench run --variant=lite --limit=10
nexus-agents swe-bench evaluate predictions.jsonl
nexus-agents swe-bench status

# Setup Claude CLI integration
nexus-agents setup                    # Auto-configure MCP + hooks + rules
nexus-agents setup --dry-run          # Preview what would be done
nexus-agents setup --skip-hooks       # Skip hook configuration

# Learning metrics dashboard
nexus-agents learning-metrics
nexus-agents learning-metrics --period=48
nexus-agents learning-metrics --bandit-stats --format=json

# Codebase index
nexus-agents index generate
nexus-agents index check
nexus-agents index diagram

# Claude CLI hooks (called by Claude Code, not user)
nexus-agents hooks session-start
nexus-agents hooks pre-tool --tool Bash --validate
nexus-agents hooks post-tool --track-metrics
nexus-agents hooks stop --check-tasks

Source Files

MCP Tools

Protocol: Model Context Protocol (2025-11-25) Transport: JSON-RPC 2.0 over stdio

Rate limiting: All tools share a single token bucket rate limiter (capacity: 100 tokens, refill: 10 tokens/sec). Each tool call consumes one token.

Tool Schemas

orchestrate

{
  "name": "orchestrate",
  "description": "Orchestrate a complex task using specialized expert agents",
  "inputSchema": {
    "type": "object",
    "properties": {
      "task": { "type": "string", "description": "Task description" },
      "context": { "type": "object", "description": "Optional context" },
      "maxIterations": { "type": "number", "default": 3 }
    },
    "required": ["task"]
  }
}

create_expert

{
  "name": "create_expert",
  "description": "Create a specialized expert agent",
  "inputSchema": {
    "type": "object",
    "properties": {
      "role": {
        "type": "string",
        "enum": [
          "code_expert",
          "architecture_expert",
          "security_expert",
          "documentation_expert",
          "testing_expert",
          "devops_expert",
          "research_expert",
          "pm_expert",
          "ux_expert",
          "infrastructure_expert"
        ]
      },
      "modelPreference": { "type": "string", "description": "Preferred model tier" }
    },
    "required": ["role"]
  }
}

run_workflow

{
  "name": "run_workflow",
  "description": "Execute a predefined workflow template",
  "inputSchema": {
    "type": "object",
    "properties": {
      "template": { "type": "string", "description": "Workflow template name" },
      "inputs": { "type": "object", "description": "Workflow inputs" },
      "dryRun": { "type": "boolean", "default": false }
    },
    "required": ["template"]
  }
}

delegate_to_model

{
  "name": "delegate_to_model",
  "description": "Route a task to the optimal model based on capabilities",
  "inputSchema": {
    "type": "object",
    "properties": {
      "task": { "type": "string", "description": "Task description" },
      "preferredCapability": { "type": "string", "enum": ["reasoning", "code", "speed", "cost"] }
    },
    "required": ["task"]
  }
}

list_experts

{
  "name": "list_experts",
  "description": "List available expert types that can be created with create_expert",
  "inputSchema": {
    "type": "object",
    "properties": {
      "format": { "type": "string", "enum": ["full", "names"], "default": "full" }
    }
  }
}

list_workflows

{
  "name": "list_workflows",
  "description": "List available workflow templates that can be executed with run_workflow",
  "inputSchema": {
    "type": "object",
    "properties": {
      "category": { "type": "string", "description": "Filter by category" },
      "format": { "type": "string", "enum": ["full", "names"], "default": "full" }
    }
  }
}

execute_expert

{
  "name": "execute_expert",
  "description": "Execute a task using a previously created expert agent",
  "inputSchema": {
    "type": "object",
    "properties": {
      "expertId": { "type": "string", "description": "Expert ID from create_expert tool" },
      "task": { "type": "string", "description": "Task description for the expert to execute" },
      "context": { "type": "object", "description": "Additional context metadata" }
    },
    "required": ["expertId", "task"]
  }
}

consensus_vote

{
  "name": "consensus_vote",
  "description": "Execute multi-model consensus voting on a proposal",
  "inputSchema": {
    "type": "object",
    "properties": {
      "proposal": { "type": "string", "description": "Proposal text to vote on" },
      "threshold": {
        "type": "string",
        "enum": ["majority", "supermajority", "unanimous"],
        "description": "Legacy threshold (use strategy instead)"
      },
      "strategy": {
        "type": "string",
        "enum": [
          "simple_majority",
          "supermajority",
          "unanimous",
          "proof_of_learning",
          "higher_order"
        ]
      },
      "quickMode": {
        "type": "boolean",
        "default": false,
        "description": "Use 3 agents instead of 5"
      },
      "simulateVotes": { "type": "boolean", "default": false, "description": "Use simulated votes" }
    },
    "required": ["proposal"]
  }
}

research_query

{
  "name": "research_query",
  "description": "Query the research registry for technique status, overlaps, statistics, or text search",
  "inputSchema": {
    "type": "object",
    "properties": {
      "action": { "type": "string", "enum": ["status", "overlap", "stats", "search"] },
      "techniqueId": { "type": "string", "description": "Technique ID for status/overlap queries" },
      "query": { "type": "string", "description": "Search query string for search action" },
      "status": {
        "type": "string",
        "enum": ["implemented", "planned", "not-started", "rejected", "all"],
        "default": "all"
      },
      "threshold": { "type": "number", "description": "Overlap threshold (0-1) for overlap action" }
    },
    "required": ["action"]
  }
}

research_add

{
  "name": "research_add",
  "description": "Add an arXiv paper to the research registry",
  "inputSchema": {
    "type": "object",
    "properties": {
      "arxivId": {
        "type": "string",
        "pattern": "^\\d{4}\\.\\d{4,5}$",
        "description": "arXiv paper ID (e.g., \"2401.12345\")"
      },
      "topic": { "type": "string", "description": "Research topic to categorize the paper under" },
      "priority": { "type": "string", "enum": ["P1", "P2", "P3", "P4"] },
      "dryRun": { "type": "boolean", "default": false, "description": "Preview without persisting" }
    },
    "required": ["arxivId"]
  }
}

research_discover

{
  "name": "research_discover",
  "description": "Discover new research papers and repositories from external sources",
  "inputSchema": {
    "type": "object",
    "properties": {
      "topic": { "type": "string", "description": "Research topic to search for" },
      "source": {
        "type": "string",
        "enum": [
          "arxiv",
          "github",
          "google_ai",
          "meta_fair",
          "microsoft",
          "deepmind",
          "semantic_scholar",
          "papers_with_code",
          "openalex",
          "all"
        ]
      },
      "maxResults": { "type": "number", "description": "Max results (1-20)" },
      "sinceDate": { "type": "string", "description": "Only results after this date (YYYY-MM-DD)" },
      "relevanceThreshold": { "type": "number", "description": "Minimum relevance score (0-1)" }
    },
    "required": ["topic"]
  }
}

research_analyze

{
  "name": "research_analyze",
  "description": "Analyze the research registry for gaps, trends, priorities, stale entries, or coverage",
  "inputSchema": {
    "type": "object",
    "properties": {
      "focus": { "type": "string", "enum": ["gaps", "trends", "priorities", "stale", "coverage"] },
      "topic": { "type": "string", "description": "Optional topic filter" }
    },
    "required": ["focus"]
  }
}

research_catalog_review

{
  "name": "research_catalog_review",
  "description": "Review auto-cataloged research references found during tool execution",
  "inputSchema": {
    "type": "object",
    "properties": {
      "action": { "type": "string", "enum": ["list", "approve", "dismiss", "flush"] },
      "identifier": { "type": "string", "description": "Reference identifier for approve/dismiss" },
      "topic": { "type": "string", "description": "Topic for approved papers" },
      "createIssue": {
        "type": "boolean",
        "default": false,
        "description": "Create GitHub issue when approving"
      }
    },
    "required": ["action"]
  }
}

memory_query

{
  "name": "memory_query",
  "description": "Query across all memory backends with unified results",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": { "type": "string", "description": "Search query to match against memory contents" },
      "limit": { "type": "number", "default": 10, "description": "Maximum results (1-50)" },
      "source": {
        "type": "string",
        "enum": ["session", "belief", "agentic", "typed", "all"],
        "default": "all"
      }
    },
    "required": ["query"]
  }
}

memory_stats

{
  "name": "memory_stats",
  "description": "Memory system statistics dashboard",
  "inputSchema": {
    "type": "object",
    "properties": {
      "includeDecay": {
        "type": "boolean",
        "default": true,
        "description": "Include decay statistics"
      },
      "includePromotion": {
        "type": "boolean",
        "default": true,
        "description": "Include promotion pipeline stats"
      }
    }
  }
}

issue_triage

{
  "name": "issue_triage",
  "description": "Triage a GitHub issue using the full security pipeline",
  "inputSchema": {
    "type": "object",
    "properties": {
      "issueUrl": {
        "type": "string",
        "description": "GitHub issue URL (e.g., https://github.com/owner/repo/issues/123)"
      },
      "dryRun": {
        "type": "boolean",
        "default": true,
        "description": "If true, returns proposed actions without executing them"
      }
    },
    "required": ["issueUrl"]
  }
}

run_graph_workflow

{
  "name": "run_graph_workflow",
  "description": "Execute a predefined graph-based workflow with checkpointing, event streaming, and audit trail support",
  "inputSchema": {
    "type": "object",
    "properties": {
      "workflow": {
        "type": "string",
        "description": "Workflow name: echo, pipeline, code-review, security-scan"
      },
      "inputs": {
        "type": "object",
        "description": "Input values for the workflow"
      },
      "enableCheckpointing": {
        "type": "boolean",
        "default": true,
        "description": "Enable checkpoint saving between steps"
      },
      "enableAuditTrail": {
        "type": "boolean",
        "default": false,
        "description": "Enable audit trail event logging"
      }
    },
    "required": ["workflow"]
  }
}

weather_report

{
  "name": "weather_report",
  "description": "Get multi-CLI performance weather report with per-CLI success rates and adaptive routing bonuses",
  "inputSchema": {
    "type": "object",
    "properties": {
      "cli": {
        "type": "string",
        "enum": ["claude", "gemini", "codex"],
        "description": "Filter by CLI"
      },
      "category": {
        "type": "string",
        "enum": [
          "architecture",
          "code_generation",
          "code_review",
          "research",
          "security_review",
          "planning",
          "documentation",
          "testing",
          "devops",
          "exploration"
        ]
      },
      "includeAdaptive": {
        "type": "boolean",
        "default": true,
        "description": "Include adaptive routing bonuses"
      }
    }
  }
}

execute_spec

{
  "name": "execute_spec",
  "description": "Execute an AI software factory spec through the full pipeline (parse, decompose, compile, execute, validate)",
  "inputSchema": {
    "type": "object",
    "properties": {
      "spec": { "type": "string", "description": "Spec content in markdown format" },
      "dryRun": { "type": "boolean", "default": false, "description": "Validate without executing" }
    },
    "required": ["spec"]
  }
}

registry_import

{
  "name": "registry_import",
  "description": "Add an AI model to the registry. Generates a draft ModelCapability entry with conservative quality scores for human review",
  "inputSchema": {
    "type": "object",
    "properties": {
      "provider": {
        "type": "string",
        "enum": ["anthropic", "google", "openai"],
        "description": "Model provider"
      },
      "modelId": { "type": "string", "description": "Provider model identifier" },
      "dryRun": { "type": "boolean", "default": true, "description": "Preview without persisting" }
    },
    "required": ["provider", "modelId"]
  }
}

Built-in Workflow Templates

9 built-in templates are available (source: src/workflows/template-types.ts):

Source Files

Programmatic API

Package: nexus-agents Entry Point: import { ... } from 'nexus-agents'

Core Exports

// Result Pattern
import { ok, err, isOk, isErr, map, mapErr, unwrap } from 'nexus-agents';

// Errors
import {
  NexusError,
  ValidationError,
  ConfigError,
  ModelError,
  AgentError,
  WorkflowError,
  SecurityError,
  TimeoutError,
} from 'nexus-agents';

// Configuration
import { AppConfigSchema, defaultConfig, type AppConfig } from 'nexus-agents';

Model Adapters

import {
  // Factory functions
  createClaudeAdapter,
  createOpenAIAdapter,
  createGeminiAdapter,
  createOllamaAdapter,
  AdapterFactory,

  // Classes
  ClaudeAdapter,
  OpenAIAdapter,
  GeminiAdapter,
  OllamaAdapter,

  // Types
  type IModelAdapter,
  type CompletionRequest,
  type CompletionResponse,
} from 'nexus-agents';

Agents & Experts

import {
  // Core agents
  Orchestrator, // preferred (TechLead still available as deprecated alias)
  Expert,
  ExpertFactory,

  // Built-in experts
  CodeExpert,
  SecurityExpert,
  ArchitectureExpert,
  TestingExpert,
  DocumentationExpert,

  // Selection utilities
  selectExperts,
  analyzeTask,

  // Types
  type Task,
  type TaskResult,
  type ExecutionPlan,
} from 'nexus-agents';

Workflows

import {
  // Parsing
  parseWorkflowYaml,
  loadWorkflowFile,
  validateWorkflow,

  // Templates
  BUILT_IN_TEMPLATES,
  createTemplateRegistry,

  // Types
  type WorkflowDefinition,
  type WorkflowStep,
  type WorkflowResult,
} from 'nexus-agents';

MCP Server

import {
  // Server creation
  createServer,
  startStdioServer,

  // Tool registration
  registerTools,
  registerOrchestrateTool,
  registerCreateExpertTool,
  registerRunWorkflowTool,

  // Types
  type ServerConfig,
  type ServerInstance,
} from 'nexus-agents';

CLI Adapters

import {
  // Adapter creation
  createCliAdapter,
  createAllAdapters,
  getAvailableClis,

  // Adapter classes
  ClaudeCliAdapter,
  GeminiCliAdapter,
  CodexCliAdapter,

  // Routing
  CompositeRouter,
  createCompositeRouter,

  // Detection
  CliDetectionCache,
  createCliDetectionCache,

  // Types
  type ICliAdapter,
  type CliTask,
  type CliResponse,
} from 'nexus-agents';

Context & Memory

import {
  // Token counting
  TokenCounter,
  createTokenCounter,

  // Context management
  ContextManager,

  // Types
  type ITokenCounter,
  type TokenCountResult,
} from 'nexus-agents';

Observability

import {
  // Orchestration observation (renamed from SwarmObserver in v2.24)
  OrchestrationObserver,
  createOrchestrationObserver,

  // Audit logging
  AuditLogger,
  createAuditLogger,

  // Types
  type IOrchestrationObserver,
  type IAuditLogger,
} from 'nexus-agents';

Learning & Feedback

import {
  // Feedback collection
  OutcomeFeedbackCollector,
  createOutcomeFeedbackCollector,

  // Integration
  FeedbackIntegration,
  createFeedbackIntegration,

  // Utilities
  computeOutcomeReward,

  // Types
  type TaskOutcome,
  type ComputedReward,
} from 'nexus-agents';

Quick Start Examples

MCP Server Mode

import { startStdioServer } from 'nexus-agents';

await startStdioServer({
  name: 'my-server',
  version: '1.0.0',
});

Programmatic Usage

import { createClaudeAdapter, createOrchestrator } from 'nexus-agents';

const adapter = createClaudeAdapter({ model: 'claude-sonnet-4-6' });
const orchestrator = createOrchestrator({ adapter });
const result = await orchestrator.execute({
  description: 'Analyze this codebase for security issues',
});

if (result.ok) {
  console.log(result.value.summary);
}

Source Files

Machine-Parseable Reference

cli_commands:
  - name: help
    flags: ['--help', '-h']
    mode: any
  - name: version
    flags: ['--version', '-v']
    mode: any
  - name: doctor
    mode: any
  - name: config init
    mode: any
  - name: expert list
    mode: any
  - name: workflow list
    mode: any
  - name: workflow run
    args: ['<template>']
    mode: orchestrator
  - name: server
    flags: ['--interactive']
    mode: server
  - name: review
    args: ['<url>']
    mode: orchestrator
  - name: routing-audit
    args: ['<task>']
    flags: ['--format', '--verbose', '--dry-run']
    mode: any
  - name: orchestrate
    args: ['<task>']
    mode: orchestrator
  - name: system-review
    flags: ['--create-issue', '--fix', '--verbose']
    mode: any
  - name: setup
    flags:
      ['--non-interactive', '--force', '--skip-mcp', '--skip-rules', '--skip-hooks', '--dry-run']
    mode: any
  - name: learning-metrics
    flags: ['--period', '--format', '--bandit-stats', '--export']
    mode: any
  - name: index
    subcommands: ['generate', 'check', 'diagram', 'validate', 'entrypoints', 'freshness', 'links']
    mode: any
  - name: hooks
    subcommands: ['session-start', 'session-end', 'pre-tool', 'post-tool', 'stop']
    mode: any
  - name: vote
    args: ['<proposal>']
    flags: ['--threshold', '--quick', '--strategy']
    mode: orchestrator
  - name: fitness-audit
    flags: ['--format', '--verbose']
    mode: any
  - name: research
    subcommands: ['query', 'add', 'discover', 'analyze']
    mode: any
  - name: release-validate
    flags: ['--version', '--verbose', '--strict', '--skip']
    mode: any
  - name: verify
    flags: ['--verbose']
    mode: any

mcp_tools:
  rate_limiting: shared token bucket (capacity: 100, refill: 10/sec)
  tools:
    - name: orchestrate
      auth: none
    - name: create_expert
      auth: none
    - name: execute_expert
      auth: none
    - name: run_workflow
      auth: none
    - name: delegate_to_model
      auth: none
    - name: consensus_vote
      auth: none
    - name: list_experts
      auth: none
    - name: list_workflows
      auth: none
    - name: research_query
      auth: none
    - name: research_add
      auth: none
    - name: research_discover
      auth: none
    - name: research_analyze
      auth: none
    - name: research_catalog_review
      auth: none
    - name: memory_query
      auth: none
    - name: memory_stats
      auth: none
    - name: issue_triage
      auth: none
    - name: run_graph_workflow
      auth: none
    - name: weather_report
      auth: none
    - name: execute_spec
      auth: none
    - name: registry_import
      auth: none

Cross-References

• CLAUDE.md - Quick Reference section links here
• README.md - Installation links here for “full reference”
• ARCHITECTURE.md - Interface Layer section links here

Generated per Process Automation Proposal #3 (Issue #210) Approved by 5-agent consensus vote (8.6/10, unanimous)