Your first task

A focused tutorial: install → verify → run a real consensus vote → wire it into your editor. About 5 minutes if you have Node 22; less if everything’s already installed.

This is the canonical new-user path. If you want platform-specific install details, jump to INSTALLATION.md. If you want every knob enumerated, jump to CONFIGURATION.md. For Claude Code plugin install specifically, see PLUGIN_INSTALL.md. Everything below stays on the canonical “first 5 minutes” path.

CLI vs MCP — read this first. The standalone CLI surface (vote, orchestrate, review) is a useful subset you can run from any terminal. The full control plane — the run entry point plus the 46 MCP tools — lives behind setup and an MCP-aware editor (Claude Code, Cursor, etc.). If you’re an MCP user, the one command to learn is run "<goal>": it’s read-only by default (pass execute: true to actually run), and the MetaOrchestrator picks the strategy for you, so you rarely pick a pipeline tool by hand. Note run is MCP-only — it is not a CLI command.

1. Install

npm install -g nexus-agents

If you hit EACCES on Linux/macOS, configure a user-local npm prefix instead of using sudo (details).

For Claude Code, you can install as a plugin instead:

/plugin install nexus-agents

2. Verify

nexus-agents doctor

Prints a health table (illustrative example output — your versions and counts will differ):

Nexus Agents Doctor
===================

Checking environment...

✓ Node.js version: v22.x.x
⚠ API keys configured: 0 of 3
  Set ANTHROPIC_API_KEY, OPENAI_API_KEY, or GOOGLE_AI_API_KEY

Checking CLI installations...

✓ Claude CLI    Version: 2.x  Auth: CLI auth
✓ Codex CLI     Version: 0.x  Auth: CLI auth
⚠ Gemini CLI    Auth: Not authenticated   Fix: gemini

Read-only; safe to run any time. If you have at least one working CLI (claude / codex / gemini), you can run the next step without setting any API keys — nexus-agents will use whatever CLI is configured.

3. Run a real consensus vote (no API keys needed)

nexus-agents vote --quick --proposal "Use SQLite over JSON files for the outcome store"

Three voter roles (architect, security, scope_steward) deliberate via whichever local CLIs you have. Expected output:

Nexus Agents Consensus Vote
============================

Collecting votes from 3 agents (timeout: 60s each)...

Proposal: Use SQLite over JSON files for the outcome store

Votes

  ✓ Software Architect: APPROVE (86%)
  ✓ Security Engineer:  APPROVE (74%)
  ✓ Scope Steward:      APPROVE (91%)

Summary

  Approve:  3
  Reject:   0
  Abstain:  0
  Approval: 100.0%
  Threshold: simple_majority

Result: APPROVED

Completed in ~30s

That’s the smoke task. The verdict prints; the vote tally and per-voter confidence are recorded. For the richer 7-voter version (which also demonstrates mixed APPROVE/REJECT outcomes and graceful error handling), see the project site hero.

4. Wire into your editor (optional but recommended)

nexus-agents setup

Auto-configures nexus-agents as an MCP server in Claude Code, Cursor, OpenCode, Gemini, and Codex (whichever you have). Restart the editor; the 46 MCP tools (orchestrate, consensus_vote, research_synthesize, verify_audit_chain, …) become available to whatever agent you’re already using.

setup writes/updates up to seven things — each opt-outtable with the corresponding --skip-* flag. The full breakdown is in the project README; if you’d rather configure one CLI at a time, run setup --interactive (the default).

5. Try a real task

# Run a real orchestration task (uses an API key if available)
export ANTHROPIC_API_KEY=your-key
nexus-agents orchestrate "Explain the architecture of this codebase"

Or via the MCP tool (after setup):

In Claude Code: /orchestrate "Explain the architecture of this codebase"

The multi-stage CompositeRouter picks the right CLI, the right expert persona, and the right model based on task analysis. The trace goes to <repo>/.nexus-agents/traces/ for later replay (traces/ is per-repo state — epic #2872).

nexus-agents writes per-repo state to <repo>/.nexus-agents/ (auto-gitignored and created on first use) and shared, cross-repo state to ~/.nexus-agents/. Run nexus-agents doctor to see the resolved paths for your environment.

Where to go next