Climux

Unified CLI multiplexer for AI coding agents

Climux provides a single interface for AI agents to orchestrate multiple coding CLI tools (Claude Code, Codex, Gemini CLI, OpenCode). Instead of learning each tool's unique syntax, agents use one consistent API.

Why Climux?

• One Interface: Single command syntax for all providers
• Smart Routing: Automatically selects the best CLI for each task type
• Session Persistence: Resume interrupted work across restarts
• Parallel Workspaces: Isolate work with git worktrees
• Cost Tracking: Monitor token usage and API costs
• Graceful Fallback: Automatic provider switching when one fails

Installation

# Global install
npm install -g @veithly/climux

# Or run directly with npx
npx @veithly/climux run "your task"

Prerequisites: At least one CLI must be installed:

npm install -g @anthropic-ai/claude-code   # Claude Code
npm install -g @openai/codex               # Codex
npm install -g @google/gemini-cli          # Gemini CLI
npm install -g opencode                    # OpenCode

Usage

Run a Task

# Auto-route to best provider
climux run "add user authentication with JWT"

# Specify provider
climux run "fix the login bug" --provider codex

# Run autonomously (non-interactive)
climux run "refactor database layer" --mode task

# Run in background
climux run "implement caching" --background

Session Management

climux session list                        # List all sessions
climux session list --status active        # Filter by status
climux session resume <id>                 # Resume session
climux session show <id>                   # Show session details
climux session log <id>                    # View conversation log
climux session export <id> --format md     # Export to markdown
climux session delete <id>                 # Delete session

Workspace Management

climux workspace info                      # Current workspace info
climux workspace list                      # List known workspaces
climux workspace switch /path/to/project   # Switch workspace
climux workspace alias api ~/projects/api  # Create alias
climux run "task" --workspace @api         # Use alias

Git Worktree Integration

climux worktree create feature-auth        # Create worktree
climux worktree create hotfix -b main      # From specific branch
climux worktree list                       # List worktrees
climux worktree switch feature-auth        # Switch to worktree
climux worktree delete feature-auth        # Delete worktree

Monitoring

climux status                              # Real-time status
climux stats                               # Today's summary
climux stats --by provider                 # Per-provider breakdown
climux stats --from 2024-01-01             # Historical data

Configuration

climux config show                         # Show current config
climux config show --providers             # Show provider status
climux config set defaultProvider codex    # Set default
climux config init                         # Initialize config

Configuration File

Global: ~/.climux/config.yaml

defaultProvider: claude-code

routing:
  - pattern: "frontend|react|vue|css"
    provider: gemini-cli
  - pattern: "debug|fix|bug|error"
    provider: codex
  - pattern: ".*"
    provider: claude-code

fallbackOrder:
  - claude-code
  - codex
  - gemini-cli
  - opencode

concurrency:
  maxActiveSessions: 5
  maxSessionsPerWorkspace: 3

monitoring:
  trackTokens: true
  trackCost: true

Project-level: .climux/config.yaml (overrides global)

defaultProvider: gemini-cli

presets:
  quick-fix:
    mode: task
    provider: claude-code

MCP Server

Climux can run as an MCP server, allowing other AI systems to use it as a tool:

climux mcp serve

Available MCP Tools:

Tool	Description
run_task	Execute a coding task
session_list	List sessions
session_resume	Resume a session
session_send	Send message to active session
get_status	Get system status
worktree_create	Create git worktree
worktree_list	List worktrees
get_session_stats	Get statistics

MCP Client Example:

const result = await client.callTool('run_task', {
  task: 'add input validation',
  mode: 'task',
  workspace: '/path/to/project'
});

Skills & MCP Management

climux skill list                          # List available skills
climux skill sync                          # Sync skills across providers
climux mcp list                            # List installed MCPs
climux mcp install <package>               # Install MCP package

For AI Agents

See SKILL.md for detailed agent instructions.

Quick Reference

# Parallel feature development
climux worktree create feature-x
climux run "implement feature X" --worktree feature-x --mode task

# Check before starting heavy work
climux status

# Monitor costs
climux stats --by provider

# Resume interrupted work
climux session list --status paused
climux session resume <id>

# Export for documentation
climux session export <id> --format md > session.md

Best Practices

1. Use --mode task for autonomous operations
2. Create worktrees for parallel development
3. Check climux status before resource-intensive tasks
4. Use aliases for frequent projects (@api, @web)
5. Monitor costs with climux stats

Data Storage

• Config: ~/.climux/config.yaml
• Database: ~/.climux/climux.db (SQLite)
• Tables: sessions, session_logs, session_stats, workspace_aliases

Error Handling

Error	Cause	Solution
PROVIDER_NOT_AVAILABLE	CLI not installed	Install or auto-fallback
SESSION_NOT_FOUND	Invalid session ID	List sessions
PROCESS_CRASHED	CLI crashed	Auto-resume
RATE_LIMITED	API limit hit	Auto-fallback

Development

git clone https://github.com/veithly/climux.git
cd climux
pnpm install
pnpm build
pnpm test

License

MIT