Nexus CLI

Smart Routing, Perfect Match.

Intelligent Task Router for Claude Code - Automatically route development tasks to the most suitable AI executor (Claude, Gemini, or Codex) based on task characteristics.

Features

Smart Task Routing: AI-powered analysis to select the optimal executor for each task
Multi-Executor Support: Seamlessly integrate Claude, Gemini CLI, and Codex CLI via PAL MCP
Structured Workflow: Spec-first approach with requirements → design → implementation phases
Batch Execution: Atomic task decomposition (≤5 min each) with parallel execution
Real-time Progress: TodoWrite integration for live progress tracking
AI Code Review: Intelligent code review powered by PAL MCP
YOLO Mode: Silent execution mode that skips all confirmations for rapid development

Platform Support

Platform	Status
macOS	✅ Fully Supported
Windows	🚧 Coming This Week
Linux	🔜 Planned

Requirements

Claude Code installed and configured
PAL MCP Server for Gemini/Codex CLI integration (optional, enables multi-executor routing)

Installation

# Clone the repository
git clone https://github.com/CoderMageFox/nexus-cli.git
cd nexus-cli

# Run the installer
./install-nexus-skill.sh

The installer will:

Register Nexus as a Claude Code skill at ~/.claude/commands/nexus.md
Create default configuration file .nexus-config.yaml
Check for optional dependencies (PAL MCP, Gemini CLI, Codex CLI)

PAL MCP Configuration (Optional)

To enable multi-executor routing, add PAL MCP to ~/.claude.json:

{
  "mcpServers": {
    "pal": {
      "command": "bash",
      "args": ["-c", "for p in $(which uvx 2>/dev/null) $HOME/.local/bin/uvx $HOME/.cargo/bin/uvx /opt/homebrew/bin/uvx /usr/local/bin/uvx uvx; do [ -x \"$p\" ] && exec \"$p\" --from git+https://github.com/BeehiveInnovations/pal-mcp-server.git pal-mcp-server; done; echo \"uvx not found\" >&2; exit 1"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key"
      }
    }
  }
}

Optional: Install Gemini CLI / Codex CLI

These CLIs are required if you enable the gemini / codex executors via PAL clink.

Gemini CLI (requires Node.js 20+):

npm install -g @google/gemini-cli@latest
# or (macOS/Linux)
brew install gemini-cli

Codex CLI:

npm install -g @openai/codex
# or (macOS)
brew install --cask codex

Installation Guide for AI Assistants

Note: This section is intended for AI coding assistants (Claude Code, Cursor, etc.) to help users install Nexus CLI.

Copy & Paste to Your AI Assistant

Simply copy the text below and send it to Claude Code, Codex, or any AI coding assistant:

English:

Help me install Nexus CLI.

For quick install, run:
mkdir -p ~/.claude/commands && curl -fsSL https://raw.githubusercontent.com/CoderMageFox/nexus-cli/main/commands/nexus.md -o ~/.claude/commands/nexus.md

For full install with dependency check, run:
cd ~/.claude && git clone https://github.com/CoderMageFox/nexus-cli.git skills/nexus-cli && ~/.claude/skills/nexus-cli/install-nexus-skill.sh

After installation, verify with: ls ~/.claude/commands/nexus.md

中文:

帮我安装 Nexus CLI。

快速安装，运行：
mkdir -p ~/.claude/commands && curl -fsSL https://raw.githubusercontent.com/CoderMageFox/nexus-cli/main/commands/nexus.md -o ~/.claude/commands/nexus.md

完整安装（包含依赖检查），运行：
cd ~/.claude && git clone https://github.com/CoderMageFox/nexus-cli.git skills/nexus-cli && ~/.claude/skills/nexus-cli/install-nexus-skill.sh

安装后验证：ls ~/.claude/commands/nexus.md

Method 1: One-Line Install (Fastest)

Download the skill file directly - no cloning required:

mkdir -p ~/.claude/commands && curl -fsSL https://raw.githubusercontent.com/CoderMageFox/nexus-cli/main/commands/nexus.md -o ~/.claude/commands/nexus.md

⚠️ Note: This method only installs the core skill file. Dependencies (PAL MCP, Gemini CLI, Codex CLI) must be installed separately if needed.

Method 2: Full Install with Configuration (Recommended)

Includes interactive configuration wizard and automatic dependency installation:

cd ~/.claude && git clone https://github.com/CoderMageFox/nexus-cli.git skills/nexus-cli && ~/.claude/skills/nexus-cli/install-nexus-skill.sh

✅ This method will:

Install the Nexus skill
Check and install missing dependencies (PAL MCP, Gemini CLI, Codex CLI, jq, uv)
Generate customized .nexus-config.yaml
Configure quality gates and executor preferences

Comparison

Feature	One-Line Install	Full Install
Speed	⚡ Fastest	🐢 ~2 min
Dependencies	❌ Manual	✅ Auto-install
Configuration	❌ Default only	✅ Interactive wizard
Best for	Quick start, CI/CD	First-time setup

Step-by-Step for AI Assistants

Check Platform: Verify user is on macOS (Windows support coming soon)
```
uname -s  # Should return "Darwin" for macOS
```
Choose Install Method:
- New users → Use Full Install (Method 2)
- Experienced users / just need the skill → Use One-Line Install (Method 1)

Verify Installation:

ls -la ~/.claude/commands/nexus.md  # Should exist after installation

Check Dependencies (if using One-Line Install):

# Optional: Install PAL MCP for multi-executor support
# Add to ~/.claude.json under mcpServers

Post-Installation: The /nexus command will be available in Claude Code after restarting the session.

Usage

In Claude Code, invoke Nexus with:

/nexus <your task description>

Examples

# Full workflow with spec generation
/nexus Create a user authentication system with JWT tokens

# Skip spec phase for simple tasks
/nexus Create a hello world function --skip-spec

# YOLO mode - silent execution, skip all confirmations
/nexus Build a login page --yolo

# Frontend task (routes to Gemini)
/nexus Build a responsive login form component

# Backend task (routes to Codex)
/nexus Implement REST API endpoints for user management

Command Flags

Flag	Description
`--skip-spec`	Skip the Spec flow (requirements, design, tasks)
`--yolo` / `--YOLO`	Silent execution mode - skip all user confirmations

Workflow

┌─────────────────────────────────────────────────────────────┐
│              Phase 0: PAL MCP Availability Check            │
│         Available → Normal Mode | Unavailable → Claude-Only │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                    SPEC Flow (Phase 1-3)                    │
│  Phase 1: Requirements (EARS format)                        │
│  Phase 2: Design Document                                   │
│  Phase 3: Task Breakdown (Batch format)                     │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                 Execution Flow (Phase 4-5)                  │
│  Phase 4: TodoWrite Init + User Confirmation                │
│  Phase 5: Batch Execution Loop                              │
│           ├─ Execute tasks in parallel per batch            │
│           ├─ Update TodoWrite immediately after each batch  │
│           └─ Route: Claude→Task, Gemini/Codex→PAL clink     │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│              Quality Gates (Phase 6) - Optional             │
│                     AI Code Review                          │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│              Completion Options (Phase 7)                   │
│         Acceptance Confirmation → Documentation             │
└─────────────────────────────────────────────────────────────┘

Executor Selection

Executor	Best For	Icon
Claude	Architecture design, deep analysis, security review, complex reasoning	🧠
Gemini	Frontend UI, algorithms, web search, creative tasks	💎
Codex	Backend APIs, databases, server-side logic	🔷

Configuration

Edit .nexus-config.yaml in your project root:

# Language: auto, zh-CN, en-US
language: auto

# Executor routing rules
routing:
  default_executor: claude
  rules:
    - pattern: "**/components/**"
      executor: gemini
      description: "React/Vue components"
    - pattern: "**/api/**"
      executor: codex
      description: "API endpoints"

# Execution settings
execution:
  max_parallel_tasks: 5
  task_timeout_minutes: 10
  batch_timeout_minutes: 30

# Quality gates (AI-powered)
quality_gates:
  enabled: true
  gates:
    review:
      enabled: true
      focus:
        - security
        - performance
        - quality

Mandatory Constraints

Constraint	Requirement
`FORCE_PAL_CHECK`	Must check PAL MCP availability before routing to Gemini/Codex
`FORCE_SPEC_FIRST`	Must complete Spec flow before execution (unless `--skip-spec`)
`FORCE_ATOMIC_TASKS`	Each task must be ≤5 minutes
`FORCE_BATCH_GROUPING`	Tasks must be grouped by dependencies
`FORCE_BATCH_TODOWRITE`	Must update TodoWrite immediately after each batch
`FORCE_USER_CONFIRMATION`	Must get user confirmation before execution

Scripts

Script	Description
`./install-nexus-skill.sh`	Install Nexus CLI
`./uninstall-nexus.sh`	Uninstall Nexus CLI
`./update-nexus.sh`	Update to latest version

Install Options

./install-nexus-skill.sh [options]

Options:
  --quick         Skip interactive configuration (use defaults)
  --config-only   Only generate config file, skip skill installation
  --check-deps    Check dependencies and offer to install missing
  --help          Show help message

Project Structure

nexus-cli/
├── commands/
│   └── nexus.md           # Main skill definition
├── lib/                   # Library modules
├── locales/               # i18n translations (en-US, zh-CN)
├── templates/             # Document templates
├── tests/                 # Test files
├── install-nexus-skill.sh # Installer
├── uninstall-nexus.sh     # Uninstaller
├── update-nexus.sh        # Updater
├── .nexus-config.yaml     # Configuration template
└── VERSION                # Version file

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Related Resources

Claude Code - AI-powered coding assistant
PAL MCP Server - Multi-model orchestration

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Nexus CLI

Features

Platform Support

Requirements

Installation

PAL MCP Configuration (Optional)

Optional: Install Gemini CLI / Codex CLI

Installation Guide for AI Assistants

Copy & Paste to Your AI Assistant

Method 1: One-Line Install (Fastest)

Method 2: Full Install with Configuration (Recommended)

Comparison

Step-by-Step for AI Assistants

Usage

Examples

Command Flags

Workflow

Executor Selection

Configuration

Mandatory Constraints

Scripts

Install Options

Project Structure

License

Contributing

Related Resources

About

Uh oh!

Releases

Packages

Contributors 3

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 20 Commits
assets		assets
commands		commands
lib		lib
locales		locales
templates		templates
tests		tests
.gitignore		.gitignore
.nexus-config.yaml		.nexus-config.yaml
README.md		README.md
README_CN.md		README_CN.md
VERSION		VERSION
install-nexus-skill.sh		install-nexus-skill.sh
uninstall-nexus.sh		uninstall-nexus.sh
update-nexus.sh		update-nexus.sh

CoderMageFox/nexus-cli

Folders and files

Latest commit

History

Repository files navigation

Nexus CLI

Features

Platform Support

Requirements

Installation

PAL MCP Configuration (Optional)

Optional: Install Gemini CLI / Codex CLI

Installation Guide for AI Assistants

Copy & Paste to Your AI Assistant

Method 1: One-Line Install (Fastest)

Method 2: Full Install with Configuration (Recommended)

Comparison

Step-by-Step for AI Assistants

Usage

Examples

Command Flags

Workflow

Executor Selection

Configuration

Mandatory Constraints

Scripts

Install Options

Project Structure

License

Contributing

Related Resources

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 3

Languages

Packages