NEXUS

Multi-Provider AI Orchestration with Automatic Failover

NEXUS is an execution layer that orchestrates multiple AI providers (Claude Code, Codex) with automatic failover, LLM-composed pipelines, and multi-perspective analysis. It extends the Personal AI Infrastructure (PAI) philosophy of treating AI as personalized infrastructure rather than stateless tools.

Why NEXUS?

The Problem: AI tools are powerful but fragile. A single provider going down, hitting rate limits, or producing poor output means your workflow stops.

The Solution: NEXUS treats AI providers like infrastructure—with redundancy, failover, and quality gates. If Claude fails, Codex picks up. If the output is poor, cross-evaluation catches it.

┌─────────────────────────────────────────────────────────────────┐
│  Your Intent                                                    │
│  "Analyze our authentication system for vulnerabilities"        │
└─────────────────────────────┬───────────────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  NEXUS                                                          │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐         │
│  │ Claude Code │ ──▶│   Codex     │ ──▶│   Local     │         │
│  │  (primary)  │    │ (fallback)  │    │ (fallback)  │         │
│  └─────────────┘    └─────────────┘    └─────────────┘         │
│         │                                                       │
│         ▼                                                       │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ Meta-Pipeline: Analyze → Compose → Execute → Verify      │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

Installation

# Global install (recommended)
npm install -g nexus-orchestrator

# Or with bun
bun add -g nexus-orchestrator

Requirements:

• Node.js 18+ or Bun 1.0+
• At least one AI provider CLI:
  • Claude Code: npm install -g @anthropic-ai/claude-code
  • Codex: npm install -g @openai/codex

Quick Start

# Initialize in any project
cd your-project
nexus init

# Execute a task
nexus execute "Review this codebase for security vulnerabilities"

# Check provider health
nexus status

# Run multi-perspective analysis
nexus analyze "Should we migrate to microservices?"

# Start knowledge elicitation
nexus elicit "Our system architecture decisions"

Key Features

Automatic Failover

NEXUS automatically retries with alternate providers when one fails:

Claude Code → timeout → Codex → success ✓

Configure in .nexus.json:

{
  "providers": {
    "primary": "claude-code",
    "fallback": ["codex"],
    "autoFailover": true
  }
}

Meta-Pipeline

Instead of fixed templates, NEXUS uses an LLM to compose unique execution pipelines for each request:

Intent → Analyze → Compose Pipeline → Execute Stages → Verify

For analysis tasks, the composer automatically generates dialectic pipelines:

┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│ User Advocate│  │  Pragmatist  │  │  Contrarian  │
│  "What does  │  │ "What's      │  │ "What could  │
│  the user    │  │  actually    │  │  go wrong?"  │
│  need?"      │  │  feasible?"  │  │              │
└──────┬───────┘  └──────┬───────┘  └──────┬───────┘
       │                 │                 │
       └─────────────────┼─────────────────┘
                         ▼
               ┌───────────────────┐
               │    Synthesizer    │
               │  Weighs all views │
               │  → Decision       │
               └───────────────────┘

Calibrated Cross-Evaluation

Six-dimension scoring with calibration to prevent grade inflation:

| Dimension | Weight | What It Measures | |-----------|--------|------------------| | Correctness | 25% | Factually accurate? | | Quality | 15% | Well-structured? | | Actionability | 20% | Can act on this? | | Completeness | 15% | Covers all aspects? | | Depth | 10% | Beyond surface-level? | | Clarity | 15% | Easy to understand? |

Most outputs score 5-7 (realistic), not 9-10 (inflated).

Knowledge Elicitor

For ambiguous requests, NEXUS uses Socratic questioning to extract implicit knowledge:

$ nexus elicit "Our deployment process"

Q1: What triggers a deployment in your current workflow?
> A merge to main branch

Q2: What verification happens before production?
> Unit tests, integration tests, staging deploy

[Extracting insights...]
- Deployment is merge-triggered (CI/CD pattern)
- Three-stage verification: unit → integration → staging

Commands

| Command | Description | |---------|-------------| | nexus init | Initialize NEXUS in current project | | nexus execute "<prompt>" | Execute a task with auto-failover | | nexus scan [path] | Analyze any project and suggest improvements | | nexus analyze "<topic>" | Multi-perspective analysis | | nexus elicit "<topic>" | Socratic knowledge extraction | | nexus verify [path] | Reality Anchor verification | | nexus pattern <cmd> | Fabric pattern operations | | nexus status | Check provider health | | nexus history | View execution history | | nexus observe | Observability dashboard |

Execution Modes

nexus execute "..." --mode=simple    # Fast, single provider
nexus execute "..." --mode=full      # + PAI context + cross-eval
nexus execute "..." --mode=simulate  # No API calls (testing)

Configuration

After nexus init, configure .nexus.json:

{
  "version": "1.0",
  "project": {
    "name": "my-app",
    "type": "node"
  },
  "execution": {
    "mode": "full",
    "verify": true,
    "useMetaPipeline": true
  },
  "providers": {
    "primary": "claude-code",
    "fallback": ["codex"],
    "autoFailover": true
  },
  "context": {
    "includePaiSkills": true,
    "includePaiMemory": true,
    "maxTokens": 4000
  }
}

Architecture

┌─────────────────────────────────────────────────────────────────┐
│  NEXUS Core                                                     │
├─────────────────────────────────────────────────────────────────┤
│  Meta-Pipeline          │  Provider Executor                    │
│  ├─ Intent Analyzer     │  ├─ Claude Code                       │
│  ├─ Pipeline Composer   │  ├─ Codex                             │
│  └─ Pipeline Executor   │  └─ Auto-failover                     │
├─────────────────────────────────────────────────────────────────┤
│  Swarms (16 templates)  │  Reality Anchor                       │
│  ├─ 24 agent roles      │  ├─ Deterministic tests               │
│  ├─ 23 marketing skills │  ├─ Tool-based checks                 │
│  └─ Parallel execution  │  └─ LLM critique                      │
├─────────────────────────────────────────────────────────────────┤
│  Unified Memory                                                 │
│  ├─ PAI integration (skills, hooks, memory)                     │
│  └─ Chroma vector DB                                            │
└─────────────────────────────────────────────────────────────────┘

Integration with PAI

NEXUS is designed to work seamlessly with Personal AI Infrastructure (PAI). When PAI is installed, NEXUS automatically:

• Loads your skills and workflows as context
• Reads your memory for relevant history
• Respects your hooks and preferences
• Uses your configured voice for notifications

PAI provides the personalization layer; NEXUS provides the execution layer.

PAI (who you are, what you want)
         │
         ▼
NEXUS (how to execute it reliably)
         │
         ▼
Providers (Claude, Codex, Local)

Swarm Templates

Pre-configured multi-agent teams for common tasks:

General

| Template | Agents | Use Case | |----------|--------|----------| | technicalArchitecture | Architect, Pragmatist, User Advocate, Ops, Contrarian | System design | | productDecision | User Advocate, Architect, Pragmatist, Analyst, Contrarian | Product choices | | crisisResponse | Pragmatist, User Advocate, Brand Guardian, Ethicist, Ops | Urgent situations |

Marketing (via marketingskills)

| Template | Agents | Use Case | |----------|--------|----------| | landingPageCRO | CRO Expert, Copywriter, User Advocate, Analyst | Conversion optimization | | productLaunch | Launch Strategist, Copywriter, Growth Hacker | Launch planning | | emailCampaign | Email Marketer, Copywriter, CRO Expert | Email sequences |

nexus swarm technicalArchitecture "Design auth system" --mode=full

Development

# Clone and install
git clone https://github.com/umutkeltek/nexus.git
cd nexus && bun install

# Run tests
bun test

# Run from source
bun run main.ts execute "Your task"

Changelog

v0.4.0 (2026-01-28)

• Meta-Pipeline: LLM-composed execution pipelines
• Auto-Failover: Claude → Codex automatic retry
• Global CLI: npm install -g nexus-orchestrator
• nexus init: Project-specific configuration
• Dialectic Pattern: Merged into pipeline composer
• Calibrated Scoring: 6-dimension cross-evaluation

v0.3.4 (2026-01-26)

• Execution modes (simple/full/simulate)
• Documentation rewrite

Full changelog →

Credits

• Personal AI Infrastructure (PAI) by Daniel Miessler — The philosophy and architecture that inspired NEXUS. PAI transforms AI from stateless tools into personalized infrastructure that learns and evolves with you.

• Marketing Skills by Corey Haines — 23 specialized marketing skills powering the marketing swarm templates.

License

MIT