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.

Release announcements

nexus-agents release-announce --channels blog --dry-run generates a blog preview. The default channel is blog; blog content remains available for manual publication. Automatic Bluesky posting is retired. Explicit --channels bluesky and mixed --channels blog,bluesky requests fail before generating any announcement. To announce on Bluesky, compose a post manually using the release URL and highlights.

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

Merge ratification

Generate the merge resolution diff before starting the panel, then pass it with --artifact-file. Read-only voter seats can have limited access to untracked or ignored files, and git show --remerge-diff can require writes they cannot perform. Run these commands from the checkout containing the merge head being ratified:

git show --remerge-diff --format=fuller HEAD > merge-resolution.diff
nexus-agents vote \
  --proposal "Ratify the merge resolution shown in the attached artifact." \
  --artifact-file merge-resolution.diff \
  --ratifies-pr "<pr-number>@<full-40-hex-lowercase-head-sha>" \
  --strategy supermajority \
  --error-policy absolute_quorum

Use the record ID printed by the vote with pnpm exec tsx scripts/append-ratification-record.ts --record-id <id> to prepare the committed ratification ledger. Owner ratification remains required for governor paths.

The file must contain UTF-8 text, have content, contain no NUL bytes, and be at most 256 KiB (262144 bytes). A missing, empty, binary, or oversized file fails before voting; an oversized-file error reports both its byte size and the cap. The proposal includes Artifact: <basename> sha256:<hex> <bytes> bytes, followed by the text between ===== BEGIN ARTIFACT ===== and ===== END ARTIFACT ===== markers. The existing proposalHash covers this header and content. Seats read the inlined text; this option does not grant access to the working tree or make a resolution-only diff a review of the entire PR. State the scope the panel should review in the proposal.

review

setup

routing-audit

system-review

learning-metrics

research

index

Doctor readiness

nexus-agents doctor checks local installation, configuration, and credentials; it makes no model completions. These checks do not prove an adapter can serve. doctor --deep adds learning-loop and routing diagnostics without model calls.

nexus-agents doctor --live sends one tiny prompt with a 16-token output hint (where the adapter supports it) through each eligible adapter in the existing doctor enumeration. Each completion uses the central interactive operation-class timeout, also passed to the adapter. Reaching the deadline bounds the wait and signals cancellation to supporting adapters, including CLI subprocesses. Retries and Claude’s in-family model fallback are disabled, and Claude is not probed a second time. Live checks spend generation quota and report:

• ok (<latency>ms) when nonempty content comes back.
• failed (<class>): <message> for auth, quota (including “Key limit exceeded”), timeout, sandbox, or other execution failures. Empty content also fails.
• skipped (not configured) when the CLI is absent, or skipped (credentials unavailable) when its local credential check prevents a probe. Neither result measures serving.

Failure messages are sanitized; completion content and credentials are not printed. Any failed live completion makes the exit code nonzero. When nothing is probed, the report says so and preserves the local doctor’s exit status. Skipping an adapter is not evidence that it serves. A live result measures readiness at that moment; it is not cached or a guarantee about the next call.

Gateway-served slots retain their gateway attribution; their completion proves the named gateway model serves, rather than certifying an unavailable CLI. --gateway --probe remains a separate opt-in probe of gateway model families.

Usage Examples

# Start MCP server (default)
nexus-agents

# Local health check (no model completions)
nexus-agents doctor

# Verify serving with one tiny completion per configured adapter (uses quota)
nexus-agents doctor --live

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

Audit repository targets: The run_pipeline audit template accepts a GitHub HTTP(S) URL anywhere in the task, an explicit repo: owner/name or repository: owner/name marker, or a concise owner/name / audit owner/name task. For example, Audit repo: owner/name after checking /path/to/artifact.json selects the remote repository while treating the artifact path as task context. Use a marker or GitHub URL for dotted repository names. Repeated references to the same repository are allowed; invalid, missing, or distinct conflicting targets fail before GitHub calls and produce no successful audit report. Absolute paths and paths prefixed with ./ or ../ alone do not request a repository audit. A standalone extensionless two-segment task deliberately uses the remote repository convention, even when those segments could also name a relative path.

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)