Introduction

As developers, we often juggle multiple contexts throughout our day - switching between personal projects, client work, and perhaps some experimental code on the side. Each context might require different permissions, access levels, and configurations. If you're using Claude Code, Anthropic's CLI tool for interacting with Claude, you've probably felt the pain of manually managing different settings.json configurations. That's why I built cctx - a fast, intuitive context switcher for Claude Code, inspired by the excellent kubectx tool for Kubernetes.

github.com

The Problem: Configuration Context Switching

Claude Code uses a settings.json file to control permissions, access levels, and various configurations. This is great for security and customization, but becomes cumbersome when you need different settings for different scenarios:

Work projects need restricted permissions for safety
Personal projects might need full access to your file system
Client demos require ultra-restricted settings for screen sharing
Experimental work needs different tool access

Manually editing settings.json or maintaining multiple copies quickly becomes error-prone and tedious. I needed something better.

docs.anthropic.com

Enter cctx: Fast Context Switching for Claude Code

cctx (Claude Context) brings the simplicity and speed of kubectx to Claude Code configuration management. Written in Rust for maximum performance, it allows you to switch between different Claude Code configurations with a single command:

# Switch to work context (restricted permissions)
cctx work

# Switch to personal context (full permissions)
cctx personal

# Switch back to previous context
cctx -

Design Philosophy: Predictable Defaults with Progressive Disclosure

One of the key lessons learned during development was the importance of predictable behavior. In version 0.1.1+, I completely redesigned the UX around a simple principle: predictable defaults with explicit overrides.

What This Means in Practice

Default behavior is always the same - cctx always manages user-level contexts (~/.claude/settings.json) unless explicitly told otherwise
No surprising auto-detection - The tool won't suddenly switch to project-level contexts just because you're in a different directory
Progressive disclosure - When project or local contexts are available, helpful hints guide you to them
Explicit when needed - Use --in-project or --local flags when you want to manage other context levels

This approach eliminates cognitive overhead while maintaining full functionality for advanced users.

Key Features That Make cctx Shine

🚀 Lightning Fast

Built with Rust, cctx switches contexts in milliseconds. No Python startup overhead, no Node.js dependencies - just pure speed.

🎨 Beautiful, Intuitive Interface

Color-coded output with the current context highlighted in green
Helpful emoji indicators for different context levels (👤 User, 📁 Project, 💻 Local)
Interactive fuzzy search with fzf integration or built-in finder
Clear, actionable error messages

🛡️ Security-First Design

Create separate contexts for different security requirements:

# Create a restricted work context
cctx -n work
cctx -e work  # Edit to add restrictions

# Create a demo context for screen sharing
cctx -n demo  # Ultra-restricted, read-only

📁 Simple File-Based Storage

Contexts are just JSON files stored in ~/.claude/settings/. You can edit them manually, version control them, or sync them across machines.

Real-World Usage Patterns

Here's how I use cctx in my daily workflow:

Morning Routine

# Start the day with work context
cctx work

# Check what context I'm in
cctx -c
# Output: work

Project Switching

# Working on a personal project
cctx personal

# Client calls - need to share screen
cctx demo

# Back to personal project
cctx -

Context Management

# Create a new context for a specific client
cctx -n client-acme

# Edit the context to set appropriate permissions
cctx -e client-acme

# List all contexts
cctx
# Output:
# 👤 User contexts:
#   client-acme
#   demo
#   personal
#   work (current)

Technical Implementation Highlights

Why Rust?

Performance: Instant startup and execution
Safety: Memory safety without garbage collection
Single binary: Easy distribution and installation
Great ecosystem: Excellent CLI libraries like clap and dialoguer

Architecture Decisions

File-based contexts: Each context is a separate JSON file
Atomic operations: Context switching is done by copying files
State tracking: Current and previous contexts tracked in a hidden state file
Platform compatibility: Works on Linux, macOS, and Windows

Settings Hierarchy Support

cctx respects Claude Code's settings hierarchy while keeping things simple:

# Default: user-level contexts
cctx work

# Explicit: project-level contexts
cctx --in-project staging

# Explicit: local project contexts
cctx --local debug

Getting Started

Installation is straightforward:

# From crates.io (recommended)
cargo install cctx

# Or grab a pre-built binary
# Download from https://github.com/nwiizo/cctx/releases

Create your first contexts:

# Create a personal context from current settings
cctx -n personal

# Create a restricted work context
cctx -n work
cctx -e work  # Edit to add restrictions

# Start switching!
cctx work
cctx personal
cctx -  # Switch back

What's Next?

The cctx project is actively maintained and follows Claude Code's development closely. Some ideas for the future include:

Context templates for common scenarios
Shell integration for automatic context switching
Context inheritance for shared settings
Integration with other AI coding tools

Conclusion

cctx brings the joy of quick context switching to Claude Code users. By focusing on speed, simplicity, and predictable behavior, it removes the friction from managing multiple configurations. Whether you're switching between work and personal projects, managing client-specific settings, or just want better control over your Claude Code permissions, cctx has you covered.

The project is open source and available on GitHub. If you find it useful, please consider starring the repository and contributing your own ideas and improvements. Happy context switching!

cctx is an independent open-source project and is not affiliated with Anthropic. For official Claude Code documentation and support, please visit docs.anthropic.com.