Claude Env (ccx or ccenv-cli)

Environment Orchestrator and Context Switcher for Claude Code CLI

Switch AI backends with a single command. Like nvm for Node.js, but for your Claude Code AI provider.

Why?

Every time you want to switch Claude Code from the official Anthropic API to OpenRouter, DeepSeek, or a local Ollama instance, you have to manually set environment variables. This tool eliminates that friction by letting you:

• Save provider configurations as profiles
• Switch between them with a single command
• Keep your API keys encrypted and secure
• Support multiple shells (bash, zsh, fish, PowerShell, cmd)

Zero server required - Unlike proxy-based solutions, ccx just manages environment variables.

Installation

npm install -g ccenv-cli

Quick Start

1. Create a profile

# Using a template
ccx create work --template openrouter --api-key sk-or-xxxxx

# Or use the interactive wizard
ccx setup

2. Run Claude with your profile

Easiest way (recommended):

ccx run work

This launches Claude Code directly with the profile's environment - no shell tricks needed!

Alternative: Activate in current shell

# Bash/Zsh
eval "$(ccx use work)"

# PowerShell
iex (ccx use work --shell powershell)

# Fish
ccx use work --shell fish | source

# Then run claude normally
claude

3. Switch back to official Anthropic

# Run with default settings
ccx run

# Or reset your shell environment
eval "$(ccx reset)"  # bash/zsh
iex (ccx reset --shell powershell)  # PowerShell

Web UI

Prefer a graphical interface? ccenv now includes a web-based UI for easy profile management!

Start the Web UI

# Build first (one-time setup)
npm run build

# Start web server
npm run web

# For development mode (auto-reload)
npm run web:dev

The web UI will be available at http://localhost:3000

Web UI Features

Prefer a graphical interface? ccenv now includes a web-based UI for easy profile management!

Start the Web UI

# Run the web server (development mode)
npm run web

# Or build and run
npm run build-web

The web UI will be available at http://localhost:3000

Web UI Features

• Dashboard: View all profiles and current active profile at a glance
• Create/Edit Profiles: Full form interface with template support
• One-Click Activation: Generate shell commands for any profile
• Export/Import: Share profiles with team members
• Multiple Shell Support: Generate commands for Bash, Zsh, Fish, PowerShell, and CMD

The web UI uses the same secure, encrypted storage as the CLI, so your API keys remain safe.

Commands

| Command | Description | |---------|-------------| | ccx run [profile] | Launch Claude with a profile directly | | ccx setup | Interactive profile setup wizard | | ccx create <name> | Create a new profile | | ccx list | List all profiles | | ccx show <name> | Show profile details | | ccx edit <name> | Edit an existing profile | | ccx delete <name> | Delete a profile | | ccx use <name> | Activate a profile (outputs shell script) | | ccx reset | Reset environment to default | | ccx current | Show current profile status | | ccx templates | List available provider templates | | ccx export <name> | Export profile as JSON | | ccx import <json> | Import profile from JSON |

Available Templates

| Template | Description | Default Model | |----------|-------------|---------------| | official | Anthropic Official API | claude-sonnet-4-20250514 | | openrouter | OpenRouter multi-model | anthropic/claude-sonnet-4 | | openrouter-minimax | MiniMax via OpenRouter | minimax/minimax-m1-80k | | openrouter-deepseek | DeepSeek via OpenRouter | deepseek/deepseek-chat-v3-0324 | | deepseek | DeepSeek Direct API | deepseek-chat | | gemini | Google Gemini | gemini-2.5-flash | | ollama | Local Ollama | qwen2.5-coder:latest | | lmstudio | Local LM Studio | local-model | | groq | Groq fast inference | llama-3.3-70b-versatile | | together | Together AI | Meta-Llama-3.1-70B | | custom | Custom endpoint | (your choice) |

Examples

Create profiles for different use cases

# High-stakes work with official Claude
ccx create pro --template official

# Budget-friendly coding with DeepSeek
ccx create budget --template openrouter-deepseek --api-key sk-or-xxxxx

# Local offline mode
ccx create local --template ollama

# Custom provider
ccx create myproxy --base-url http://localhost:8080/v1 --api-key my-key --model gpt-4

Shell integration (add to .bashrc/.zshrc)

# Function to switch profiles easily
ccx-switch() {
  eval "$(ccx use $1)"
  echo "Switched to profile: $1"
}

# Aliases
alias cc-pro='ccx-switch pro'
alias cc-budget='ccx-switch budget'
alias cc-local='ccx-switch local'
alias cc-reset='eval "$(ccx reset)"'

PowerShell integration (add to $PROFILE)

function Switch-Claude {
  param([string]$Profile)
  Invoke-Expression (ccx use $Profile --shell powershell)
  Write-Host "Switched to profile: $Profile"
}

Set-Alias cc-switch Switch-Claude

How It Works

1. Profiles are stored in ~/.config/claude-env/config.json (cross-platform via conf)
2. API keys are encrypted using AES-256 with a machine-specific key
3. ccx use outputs shell-specific export commands for eval
4. Environment variables set:
   • ANTHROPIC_BASE_URL - The API endpoint
   • ANTHROPIC_AUTH_TOKEN - Your API key
   • ANTHROPIC_MODEL - The model to use
   • ANTHROPIC_API_KEY - Unset when using proxies (important!)
   • CCX_ACTIVE_PROFILE - Tracks the active profile

Security

• API keys are encrypted at rest using AES-256-CBC
• Encryption key is derived from machine-specific info (hostname + username)
• Keys are never logged or exposed in plain text
• Export command excludes API keys by default

Comparison with claude-code-router

| Feature | ccx | claude-code-router | |---------|-----|-------------------| | Architecture | Env vars only | Local proxy server | | Background process | No | Yes | | Profile switching | Instant | Requires restart | | Request routing | N/A | Yes (background/think/etc) | | Custom transformers | N/A | Yes | | Complexity | Low | High |

Use ccx if: You want simple, fast profile switching without running a server.

Use claude-code-router if: You need advanced request routing or custom transformers.

Troubleshooting

"Profile not taking effect" (when using ccx use)

Make sure you're using eval or iex:

# Wrong
ccx use work

# Right
eval "$(ccx use work)"

Or just use ccx run instead - it handles everything for you:

ccx run work

"Shell not detected correctly"

Specify the shell explicitly:

ccx use work --shell zsh

"Config file location"

ccx config-path

License

MIT