ccctx

A CLI tool for managing multiple Claude Code API contexts. Switch between different API providers, models, and configurations with a single command.

How It Works

Claude Code stores environment variables (API key, base URL, model, etc.) in settings.json. ccctx manages these as named "contexts" in a separate ccctx.yaml file. When you switch contexts, ccctx writes the corresponding env vars into settings.json.

Installation

Download the binary for your platform from the Releases page:

Platform	File
macOS (Apple Silicon)	ccctx-darwin-arm64
macOS (Intel)	ccctx-darwin-amd64
Linux (x86_64)	ccctx-linux-amd64
Linux (ARM64)	ccctx-linux-arm64
Windows (x86_64)	ccctx-windows-amd64.exe

# Example: macOS Apple Silicon
curl -LO https://github.com/zoulux/ccctx/releases/latest/download/ccctx-darwin-arm64
chmod +x ccctx-darwin-arm64
mv ccctx-darwin-arm64 /usr/local/bin/ccctx

Or install with Go:

go install github.com/zoulux/ccctx@latest

Quick Start

# Import your current settings.json as the "default" context
ccctx -i

# Import with a custom name
ccctx -i my-provider

# Interactively select and switch context
ccctx

# Switch directly by name
ccctx openai

# Switch to the previous context
ccctx -

Usage

ccctx                       Interactively select a context (arrow keys + Enter)
ccctx -l, --list            List all contexts (current one highlighted)
ccctx <NAME>                Switch to context <NAME>
ccctx -                     Switch to the previous context
ccctx -c, --current         Show the current context name
ccctx -i, --import [NAME]   Import settings.json env as a context
                            (auto-detects project/user level, default name "default")
ccctx -i [NAME] -f          Overwrite an existing context
ccctx <NEW>=<OLD>           Rename context <OLD> to <NEW>
ccctx <NEW>=.               Rename current context to <NEW>
ccctx -d <NAME>             Delete context <NAME> (. for current)
ccctx -u, --unset           Unset the current context (clear env)
ccctx completion [zsh|bash] Print shell completion script
ccctx completion zsh --install  Install zsh completions
ccctx --example             Print an example ccctx.yaml

Config File

ccctx uses a YAML config file (ccctx.yaml). Generate an example:

ccctx --example

Output:

api-version: v1
current-context: anthropic
previous-context: ""
common-env:
    API_TIMEOUT_MS: "600000"
    CLAUDE_AUTOCOMPACT_PCT_OVERRIDE: "85"
    CLAUDE_CODE_MAX_OUTPUT_TOKENS: "120000"
contexts:
    - name: anthropic
      env:
        ANTHROPIC_AUTH_TOKEN: sk-ant-xxx
        ANTHROPIC_BASE_URL: https://api.anthropic.com
        ANTHROPIC_MODEL: claude-sonnet-4-6
    - name: openai
      env:
        ANTHROPIC_AUTH_TOKEN: sk-proj-xxx
        ANTHROPIC_BASE_URL: https://api.openai.com/v1
        ANTHROPIC_MODEL: gpt-5

• common-env: Shared env vars applied to all contexts (overridden by context-specific values)
• contexts: Each context has a name and its own env map

Config Priority

ccctx resolves the config path with the following priority (highest first):

Priority	Source	Config Path	Settings Path
1	Environment variable	$CCCTX_CONFIG	Same directory as $CCCTX_CONFIG
2	Project level	CWD/.claude/ccctx.yaml	CWD/.claude/settings.json
3	User level	~/.claude/ccctx.yaml	~/.claude/settings.json

When CCCTX_CONFIG is set, both the config and settings paths are resolved relative to that file. Project level is auto-detected by checking if .claude/ccctx.yaml exists in the current working directory.

Interactive Selector

Running ccctx with no arguments opens an interactive selector:

• Arrow keys (or Ctrl+P/Ctrl+N) to navigate
• Enter to confirm
• Esc or Ctrl+C to cancel
• Current context marked with a dot indicator

Acknowledgments

Inspired by kubectx — similar commands and workflow, familiar experience for kubectx users.

Shell Completion

# Print completion script
ccctx completion zsh

# Auto-install (detects shell from $SHELL)
ccctx completion --install

# Explicit shell + install
ccctx completion zsh --install
ccctx completion bash --install