🔄 cctx - Claude Context Switcher

⚡ Fast and intuitive way to switch between Claude Code contexts (~/.claude/settings.json)

cctx (Claude Context) is a kubectx-inspired command-line tool for managing multiple Claude Code configurations. Switch between different permission sets, environments, and settings with a single command.

✨ Features

• 🔀 Instant context switching - Switch between configurations in milliseconds
• 🎯 Predictable UX - Default behavior always uses user-level contexts (no surprises!)
• 🛡️ Security-first - Separate permissions for work, personal, and project contexts
• 🎨 Beautiful CLI - Colorized output with helpful hints and visual indicators
• 🚀 Shell completions - Tab completion for all major shells
• 📦 Zero dependencies - Single binary, works everywhere
• 🔄 Previous context - Quick switch back with cctx -
• 📁 File-based - Simple JSON files you can edit manually
• 🎭 Kubectx-inspired - Familiar UX for Kubernetes users
• 💡 Progressive disclosure - Shows project/local contexts when available

🚀 Quick Start

📦 Installation

From crates.io (recommended):

cargo install cctx

From source:

git clone https://github.com/nwiizo/cctx.git
cd cctx
cargo install --path .

Pre-built binaries: Download from GitHub Releases

⚡ 30-Second Setup

# 1. Create your first context from current settings
cctx -n personal

# 2. Create a restricted work context
cctx -n work

# 3. Switch between contexts
cctx work      # Switch to work
cctx personal  # Switch to personal  
cctx -         # Switch back to previous

🎯 Usage

🔍 Basic Commands

# List all contexts (current highlighted in green)
cctx

# Switch to a context
cctx work

# Switch to previous context  
cctx -

# Show current context
cctx -c

🏗️ Settings Level Management

cctx respects Claude Code's settings hierarchy with a simple, predictable approach:

1. Enterprise policies (highest priority)
2. Command-line arguments
3. Local project settings (./.claude/settings.local.json)
4. Shared project settings (./.claude/settings.json)
5. User settings (~/.claude/settings.json) (lowest priority)

# Default: always uses user-level contexts (predictable)
cctx                       # Manages ~/.claude/settings.json

# Explicit flags for project/local contexts
cctx --in-project          # Manages ./.claude/settings.json
cctx --local               # Manages ./.claude/settings.local.json

# All commands work with any level
cctx --in-project work     # Switch to 'work' in project contexts
cctx --local staging       # Switch to 'staging' in local contexts

🛠️ Context Management

# Create new context from current settings
cctx -n project-alpha

# Delete a context
cctx -d old-project

# Rename a context
cctx -r old-name new-name

# Edit context with $EDITOR
cctx -e work

# Show context content (JSON)
cctx -s production

# Unset current context
cctx -u

📥📤 Import/Export

# Export context to file
cctx --export production > prod-settings.json

# Import context from file
cctx --import staging < staging-settings.json

# Share contexts between machines
cctx --export work | ssh remote-host 'cctx --import work'

🔀 Merge Permissions

Merge permissions from other contexts or files to build complex configurations:

# Merge user settings into current context
cctx --merge-from user

# Merge from another context
cctx --merge-from personal work

# Merge from a specific file
cctx --merge-from /path/to/permissions.json staging

# Remove previously merged permissions
cctx --unmerge user

# View merge history
cctx --merge-history

# Merge into a specific context (default is current)
cctx --merge-from user production

Merge Features:

• 📋 Smart deduplication - Prevents duplicate permissions
• 📝 History tracking - See what was merged from where
• 🔄 Reversible - Unmerge specific sources anytime
• 🎯 Granular control - Target specific contexts

🖥️ Shell Completions

Enable tab completion for faster workflow:

# Bash
cctx --completions bash > ~/.local/share/bash-completion/completions/cctx

# Zsh  
cctx --completions zsh > /usr/local/share/zsh/site-functions/_cctx

# Fish
cctx --completions fish > ~/.config/fish/completions/cctx.fish

# PowerShell
cctx --completions powershell > cctx.ps1

🏗️ File Structure

Contexts are stored as individual JSON files at different levels:

🏠 User Level (~/.claude/):

📁 ~/.claude/
├── ⚙️ settings.json           # Active user context
└── 📁 settings/
    ├── 💼 work.json          # Work context  
    ├── 🏠 personal.json      # Personal context
    └── 🔒 .cctx-state.json   # State tracking

📁 Project Level (./.claude/):

📁 ./.claude/
├── ⚙️ settings.json           # Shared project context
├── 🔒 settings.local.json     # Local project context (gitignored)
└── 📁 settings/
    ├── 🚀 staging.json       # Staging context
    ├── 🏭 production.json    # Production context
    ├── 🔒 .cctx-state.json   # Project state
    └── 🔒 .cctx-state.local.json # Local state

🎭 Interactive Mode

When no arguments are provided, cctx enters interactive mode:

• 🔍 fzf integration - Uses fzf if available for fuzzy search
• 🎯 Built-in finder - Fallback fuzzy finder when fzf not installed
• 🌈 Color coding - Current context highlighted in green
• ⌨️ Keyboard navigation - Arrow keys and type-ahead search

# Interactive context selection
cctx

💼 Common Workflows

🏢 Professional Setup

# Create restricted work context for safer collaboration
cctx -n work
cctx -e work  # Edit to add restrictions:
# - Read/Edit only in ~/work/** and current directory
# - Deny: docker, kubectl, terraform, ssh, WebFetch, WebSearch
# - Basic dev tools: git, npm, cargo, python only

🚀 Project-Based Contexts

# Create project-specific contexts
cctx -n client-alpha    # For client work
cctx -n side-project    # For personal projects  
cctx -n experiments     # For trying new things

# Switch based on current work
cctx client-alpha       # Restricted permissions
cctx experiments        # Full permissions for exploration

🔄 Daily Context Switching

# Morning: start with work context
cctx work

# Need full access for personal project  
cctx personal

# Quick switch back to work
cctx -

# Check current context anytime
cctx -c

🛡️ Security-First Approach

# Default restricted context for screen sharing
cctx work

# Full permissions only when needed
cctx personal

# Project-specific minimal permissions
cctx -n client-project
# Configure: only access to ~/projects/client/** 

🎯 Settings Level Workflows

👤 User-Level Development:

# Personal development with full permissions (default behavior)
cctx personal

# Work context with restrictions (default behavior)
cctx work

📁 Project-Level Collaboration:

# Shared team settings (committed to git)
cctx --in-project staging
cctx --in-project production

# Personal project overrides (gitignored)
cctx --local development
cctx --local debug

🔄 Multi-Level Management:

# Check current level (always shows helpful context)
cctx                    # Shows: 👤 User contexts + hints for project/local if available

# Switch levels in same directory
cctx personal           # User level (default)
cctx --in-project staging  # Project level  
cctx --local debug      # Local level

🔧 Advanced Usage

📝 Context Creation with Claude

Use Claude Code to help create specialized contexts:

# Create production-safe context
claude --model opus <<'EOF'
Create a production.json context file with these restrictions:
- Read-only access to most files
- No docker/kubectl/terraform access  
- No system file editing
- Limited bash commands for safety
- Based on my current ~/.claude/settings.json but secured
EOF

🎨 Custom Context Templates

# Create template contexts for different scenarios
cctx -n template-minimal     # Minimal permissions
cctx -n template-dev         # Development tools only
cctx -n template-ops         # Operations/deployment tools
cctx -n template-restricted  # Screen-sharing safe

🔄 Context Synchronization

# Sync contexts across machines
rsync -av ~/.claude/settings/ remote:~/.claude/settings/

# Or use git for version control
cd ~/.claude/settings
git init && git add . && git commit -m "Initial contexts"
git remote add origin git@github.com:user/claude-contexts.git
git push -u origin main

🛡️ Security Best Practices

🔒 Permission Isolation

1. 🏢 Work context - Restricted permissions for professional use
2. 🏠 Personal context - Full permissions for personal projects
3. 📺 Demo context - Ultra-restricted for screen sharing/demos
4. 🧪 Testing context - Isolated environment for experiments

🎯 Context Strategy

# Create permission hierarchy
cctx -n restricted   # No file write, no network, no system access
cctx -n development  # File access to ~/dev/**, basic tools only  
cctx -n full        # All permissions for personal use
cctx -n demo        # Read-only, safe for presentations

🔍 Regular Audits

# Review context permissions regularly
cctx -s work        # Check work context permissions
cctx -s personal    # Review personal cont