English | 한국어

cx-skills

DEPRECATED — cx-skills has been renamed to triflux.

npm install -g triflux

All future updates will be published under the triflux package. cx-skills will no longer receive updates.

CLI-first multi-model orchestrator for Claude Code. Route tasks to Codex, Gemini, and Claude.

Don't pay Claude tokens for what Codex and Gemini can do for free.

Quick Start · Skills · Architecture · Setup Guide

Quick Start

Step 1: Install

# Option A: Claude Code Plugin (recommended)
/plugin marketplace add https://github.com/tellang/cx-skills
/plugin install cx-skills

# Option B: npm
npm install -g cx-skills

Installation Scope

| Scope | Plugin | npm | Applies To | |-------|--------|-----|------------| | User (default) | /plugin install cx-skills | npm install -g cx-skills | All projects | | Project | /plugin install cx-skills --scope project | npm install cx-skills | Current project only | | One-off | — | npx cx-skills doctor | Run without installing |

Step 2: Use

# Auto mode — AI classifies + decomposes
/cx-auto "refactor auth module + improve login UI + add tests"

# Manual mode — specify agent directly
/cx-auto 3:codex "review src/api, src/auth, src/payment"

# Codex-only (no Gemini needed)
/cx-codex "refactor + review"

# Gemini-only (no Codex needed)
/cx-gemini "implement + document"

That's it. cli-route.sh and HUD are auto-installed on first install.

Step 3: Verify (optional)

cxs doctor    # Check CLI availability + HUD status
cxs setup     # Re-sync files + configure HUD

Why cx-skills?

• Cost Optimization — Routes to Codex/Gemini (free tiers) first, Claude only when necessary
• CLI-Native — No MCP overhead; direct shell execution of Codex/Gemini CLIs
• Auto Triage — Sonnet classifies tasks, Opus decomposes into parallel subtasks
• DAG Execution — Dependency-aware parallel execution with context passing
• Zero Config — Plugin auto-installs cli-route.sh and HUD on first session
• OMC Compatible — Works standalone or as an extension alongside oh-my-claudecode

Execution Modes

| Mode | Workers | Best For | |------|---------|----------| | cx-auto (auto) | N (AI decides) | Complex multi-part tasks — AI classifies + decomposes | | cx-auto (manual) | N:agent | Direct control — you choose agent and worker count | | cx-codex | N (Codex-only) | Environments without Gemini CLI | | cx-gemini | N (Gemini-only) | Environments without Codex CLI |

Skills

Orchestration

| Skill | Description | Example | |-------|-------------|---------| | cx-auto | Unified parallel orchestrator | /cx-auto "analyze + implement + test" | | cx-codex | Codex-only orchestrator (no Gemini) | /cx-codex "refactor + review" | | cx-gemini | Gemini-only orchestrator (no Codex) | /cx-gemini "implement + document" |

CLI Commands (via cx-auto shortcuts)

| Command | Routes To | Use Case | |---------|-----------|----------| | /implement | Codex | Code implementation | | /analyze | Codex | Code analysis / debugging | | /build | Codex | Build error fixing | | /research | Codex | Technical research | | /design | Gemini | UI/UX design | | /document | Gemini | Documentation | | /test | Claude | Test execution | | /explain | Codex | Code explanation |

Setup & Utilities

| Skill | Description | |-------|-------------| | cx-setup | Initial setup — HUD config + CLI diagnostics | | auto-verify | Post-execution skill update + verification | | manage-skills | Analyze changes, create/update verify skills | | verify-implementation | Run all verify skills, generate report |

CLI Commands

| Command | Alias | Description | |---------|-------|-------------| | cx-skills help | cxs | Show help + check for updates | | cx-skills setup | cx-setup | Sync files + configure HUD statusLine | | cx-skills doctor | cx-doctor | Cross-shell CLI diagnostics | | cx-skills update | cxs update | Update to latest version | | cx-skills list | cxs list | List installed skills | | cx-skills version | cxs version | Show version info |

Architecture

Routing Strategy

User Input
    |
    +-- Agent specified? ──YES──→ [Opus Decompose] → Parallel Execution
    |
    NO
    |
    v
[Sonnet Classify]
  → codex (code), gemini (UI/docs), claude (explore/verify)
    |
    v
[Opus Decompose]
  → N independent subtasks with agent + scope
    |
    v
[cli-route.sh × N Parallel]
  → Results collection + Report

Agent → CLI Mapping

| Agent | CLI | Use Case | |-------|-----|----------| | executor, build-fixer, debugger | Codex | Code implementation / analysis | | architect, planner, critic | Codex | Design / planning | | code-reviewer, security-reviewer | Codex | Code review | | designer, writer | Gemini | UI / documentation | | explore | Claude Haiku | Codebase search | | verifier, test-engineer | Claude Sonnet | Test / verification |

DAG Execution

For tasks with dependencies, cx-auto performs topological sort and executes level-by-level:

Level 0: [research-A] [research-B]    ← parallel
Level 1: [implement]                   ← depends on L0
Level 2: [test]                        ← depends on L1

Context is passed between levels via .omc/context/{session}/ files.

Prerequisites

• Claude Code CLI
• Claude Max/Pro subscription

Optional: Multi-Model Orchestration

| Provider | Install | Use Case | |----------|---------|----------| | Codex CLI | npm install -g @openai/codex | Code implementation, analysis, review | | Gemini CLI | npm install -g @google/gemini-cli | Documentation, UI design |

Cost: ~$60/month with 3 Pro plans (Claude + Gemini + ChatGPT) covers everything. Codex and Gemini free tiers handle most workloads.

Codex / Gemini Setup

API Keys

# Codex (OpenAI)
export OPENAI_API_KEY="sk-..."
# Or with Codex Pro subscription — no additional setup needed

# Gemini (Google)
export GEMINI_API_KEY="..."
# Or authenticate via: gemini auth login

Add to your shell profile (~/.bashrc, ~/.zshrc) for auto-loading.

Verify Installation

# Codex
codex --version
codex exec --full-auto "echo hello"

# Gemini
gemini --version
gemini -p "echo hello"

Troubleshooting

| Symptom | Cause | Fix | |---------|-------|-----| | codex: command not found | Codex CLI not installed | npm install -g @openai/codex | | gemini: command not found | Gemini CLI not installed | npm install -g @google/gemini-cli | | Codex auth failure | API key missing/expired | export OPENAI_API_KEY="sk-..." | | Gemini auth failure | API key missing | export GEMINI_API_KEY="..." or gemini auth login | | Gemini hangs on Windows | node-pty compatibility | cx-skills auto-applies --timeout 60 + health check | | cli-route.sh: not found | Auto-install failed | Manual: cp scripts/cli-route.sh ~/.claude/scripts/ | | Codex timeout (300s) | Task scope too large | Split task or increase timeout: /cx-route executor "task" implement 600 | | status: failed + stderr | CLI execution error | Check /tmp/omc-route-{agent}-*-stderr.log |

Without External CLIs

cx-skills works without Codex/Gemini. Missing CLIs automatically fallback via cli-route.sh (v1.4+):

No Codex  → Codex agents reroute to Gemini (if available) or Claude native
No Gemini → Gemini agents reroute to Codex (if available) or Claude native
Neither   → All tasks run via Claude native (higher cost)

You can also force a specific mode via environment variable or dedicated skills:

# Environment variable
CX_CLI_MODE=codex bash ~/.claude/scripts/cli-route.sh executor "task" implement

# Dedicated skills
/cx-codex "task"    # Forces all external CLI work to Codex
/cx-gemini "task"   # Forces all external CLI work to Gemini

OMC Compatibility

cx-skills works standalone or alongside oh-my-claudecode (OMC):

| Setup | Behavior | |-------|----------| | cx-skills only | Full CLI routing — all skills available | | cx-skills + OMC | cx-skills handles CLI routing, OMC handles orchestration (team, autopilot, ralph) |

When both are installed, cx-skills extends OMC with direct CLI access to Codex/Gemini, bypassing MCP overhead.

Versioning

Check Current Version

# All versions at once
cxs version

# Or individually
cat ~/.claude/plugins/installed_plugins.json | grep -A5 cx-skills
head -6 ~/.claude/scripts/cli-route.sh | grep VERSION

Version Scheme

Follows Semantic Versioning:

| Change Type | Version | Example | |-------------|---------|---------| | Backward-compatible fixes | PATCH (1.0.x) | cli-route.sh error handling fix | | Backward-compatible features | MINOR (1.x.0) | New skill, new agent mapping | | Breaking changes | MAJOR (x.0.0) | Skill interface change, CLI arg change |

Changelog — cli-route.sh

| Version | Changes | |---------|---------| | v1.0 | Basic routing (Codex/Gemini/Claude branching) | | v1.1 | stderr separation, output filtering, timeout, MCP profile support | | v1.2 | Dynamic effort routing, bg/fg modes, Opus oversight, Gemini model branching | | v1.3 | Context-file support, DAG execution integration | | v1.4 | CX_CLI_MODE support (codex-only/gemini-only), auto-fallback for missing CLIs | | v1.5 | MCP inventory caching — dynamic hints based on actual server availability | | v1.6 | Token parsing from Codex JSON output, sv-accumulator.json for cost tracking | | v1.7 | Gemini -p → --prompt fix (personal prompt conflict), CLI issue auto-collection (track_cli_issue) |

Changelog — hud-qos-status.mjs

| Version | Changes | |---------|---------| | v1.7 | Gemini model-based RPM limits (Pro 25 / Flash 300), model label display, dollar-based savings accumulation | | v1.8 | sv null placeholder (--%), Gemini account|model order fix, Claude --% prevention (default 0% fallback), OMC-HUD cache sharing (429 prevention), cache path migration .omc/ → .claude/cache/ |

Changelog — cx-skills CLI

| Version | Changes | |---------|---------| | v1.9.0 | CLI issue tracker in cx-doctor (pattern detection, auto-cleanup of resolved issues) | | v1.9.1 | Terminal UI redesign — amber branding, 256-color, modern layout |

Auto-Update

The SessionStart hook compares versions and auto-syncs:

• cli-route.sh → ~/.claude/scripts/cli-route.sh
• hud-qos-status.mjs → ~/.claude/hud/hud-qos-status.mjs

Overwrites only when the plugin version is newer.

Project Structure

cx-skills/
├── bin/
│   ├── cx-skills.mjs      # Main CLI (cxs)
│   ├── cx-setup.mjs       # cx-setup shortcut
│   └── cx-doctor.mjs      # cx-doctor shortcut
├── .claude-plugin/        # Plugin registration
│   ├── plugin.json        # Plugin metadata
│   └── marketplace.json   # Marketplace listing
├── .mcp.json              # MCP server definitions
├── hooks/
│   └── hooks.json         # Lifecycle hooks (auto-setup)
├── scripts/
│   ├── cli-route.sh       # CLI routing wrapper (v1.6)
│   ├── mcp-check.mjs      # MCP inventory cache (background)
│   └── setup.mjs          # Auto-install + HUD config + banner
├── skills/
│   ├── cx-auto/           # Unified parallel orchestrator
│   ├── cx-codex/          # Codex-only orchestrator
│   ├── cx-gemini/         # Gemini-only orchestrator
│   ├── cx-setup/          # Setup + diagnostics skill
│   ├── auto-verify/       # Post-execution verification
│   ├── manage-skills/     # Skill management
│   └── verify-implementation/  # Integration verification
├── hud/
│   └── hud-qos-status.mjs # Status bar HUD (v1.7)
├── package.json
├── LICENSE
└── README.md

Update

# CLI (recommended)
cxs update

# npm global
npm update -g cx-skills

# Plugin marketplace
/plugin marketplace update cx-skills

cxs automatically checks for updates and shows a notice when a newer version is available.

If issues occur after update:

# Reinstall plugin
/plugin uninstall cx-skills
/plugin install cx-skills

# Or re-run setup
cxs setup

License

MIT