Nexus-Agents Entrypoints

Last Updated: 2026-06-02 (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]

The tables between the markers are generated from COMMAND_CATALOG (packages/nexus-agents/src/cli-command-catalog.ts), the same literal nexus-agents --help renders from, so every registered command appears here exactly once (#5458). Commands are grouped by the catalog’s audience band: essential is what a new user needs to install, configure and run a first task; advanced is day-to-day but not first-touch; maintainer is benchmarks, release tooling and deep diagnostics (--help --all); internal is dev/eval loops hidden from --help entirely. nexus-agents <command> --help prints flags and examples for any of them.

Essential — install, configure, run

Advanced — day-to-day extras

Maintainer — benchmarks, releases, deep diagnostics

Internal — dev/eval loops (hidden from –help)

Auto-generated from COMMAND_CATALOG (packages/nexus-agents/src/cli-command-catalog.ts) by scripts/inject-governance.ts. 53 commands.

Subcommands and modes

The catalog carries a name and a one-line description per command; it has no subcommand or mode field, so this table is hand-maintained and covers only the commands whose subcommand shape is not obvious from the description. Mode is the process mode the command needs (see Mode Selection below); any means it works in both.

Deprecated

Commands whose catalog description starts with [deprecated] still dispatch, but only to a migration message:

• swe-bench and atbench — harnesses extracted to nexus-substrate/nexus-eval-swebench and nexus-substrate/nexus-eval-atbench (epic #2514); shims until the next minor.
• login — soft alias of auth status (renamed in #2449).

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
nexus-agents research autofile --dry-run                            # Preview auto-filing research + gap candidates
nexus-agents research autofile --topic=agents --max=3               # File candidates as issues (safeguarded, #3382)

# Quick verification
nexus-agents verify

# PR review with setup wizard
nexus-agents review <pr-url> --setup

# Learning-validation dashboard
nexus-agents validation

# SWE-bench evaluation — DEPRECATED, see https://github.com/nexus-substrate/nexus-eval-swebench
# (the in-tree commands stub out with a migration message; harness lives in its own repo per #2514)

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

Auto-generated from REGISTERED_TOOL_NAMES + TOOL_DESCRIPTIONS by scripts/inject-governance.ts. 47 tools.

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

Graph workflow templates call no model. The run_graph_workflow templates security-audit, test-generation and documentation run local substring and regex checks over the input. No node invokes a model, CLI or adapter, and no tokens are spent. Their steps are labelled [heuristic]. Read a result as a keyword scan, not as a review by any model family (#6676). They are separate from the run_workflow templates security-audit and test-generation listed below.

Tool Schemas

Full per-tool input schemas — every parameter with its type, required/optional status, constraints (enum members, min/max, pattern, defaults), and description — live in the generated MCP Tool Reference. Those pages are generated directly from the registered Zod input schemas (pnpm docs:tools) and drift-gated in CI, so they never fall out of sync with the runtime contract.

Agents should discover schemas live via the MCP tools/list request; the generated reference is the human-readable companion.

Built-in Workflow Templates

11 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
    flags: ['--proposal', '-p', '--threshold', '--quick', '--strategy']
    mode: any
  - name: fitness-audit
    flags: ['--format', '--verbose']
    mode: any
  - name: research
    subcommands: ['query', 'add', 'discover', 'analyze']
    mode: any
  - name: release-validate
    args: ['<version>']
    flags: ['--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: list_experts
      auth: none
    - name: list_workflows
      auth: none
    - name: consensus_vote
      auth: none
    - name: research_query
      auth: none
    - name: research_add
      auth: none
    - name: research_add_source
      auth: none
    - name: research_discover
      auth: none
    - name: research_analyze
      auth: none
    - name: research_catalog_review
      auth: none
    - name: research_synthesize
      auth: none
    - name: survey_oss_landscape
      auth: none
    - name: vendor_publishing_audit
      auth: none
    - name: compare_data_feeds
      auth: none
    - name: memory_query
      auth: none
    - name: memory_stats
      auth: none
    - name: memory_write
      auth: none
    - name: weather_report
      auth: none
    - name: issue_triage
      auth: none
    - name: run_graph_workflow
      auth: none
    - name: execute_spec
      auth: none
    - name: registry_import
      auth: none
    - name: query_trace
      auth: none
    - name: query_task_state
      auth: none
    - name: get_job_result
      auth: none
    - name: list_jobs
      auth: none
    - name: cancel_job
      auth: none
    - name: ci_health_check
      auth: none
    - name: verify_audit_chain
      auth: none
    - name: repo_analyze
      auth: none
    - name: repo_security_plan
      auth: none
    - name: extract_symbols
      auth: none
    - name: search_codebase
      auth: none
    - name: search_usages
      auth: none
    - name: run_dev_pipeline
      auth: optional
    - name: run_pipeline
      auth: none
    - name: pr_review
      auth: none
    - name: supply_chain_tradeoff_panel
      auth: none
    - name: improvement_review
      auth: none
    - name: run_quality_gate
      auth: none
    - name: suggest_research_tasks
      auth: none
    - name: list_available_models
      auth: none
    - name: run
      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
• guides/COMPOSITION_PATTERNS.md - Compose execute_spec / GraphBuilder / consensus into custom pipelines

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