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

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

CoderMageFox/nexus-cli

Folders and files

Latest commit

History

Repository files navigation