CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

cc-switch is a Rust CLI tool for managing multiple Claude API configurations and automatically switching between them. The tool allows users to store different API configurations (alias, token, URL, model settings) and switch between them by modifying Claude's settings.json file. This is particularly useful for developers who need to use multiple Claude API endpoints or switch between different accounts.

The project follows Rust best practices with a library + binary structure and domain-based organization.

our program config dir is ~/.claude/cc_auto_switch_setting.json

Development Commands

Build and Run

# Build project
cargo build

# Run project
cargo run [args]

# Release build
cargo build --release

# Run release binary
cargo run --release [args]

Testing

# Run all tests (library + integration + doctests)
cargo test

# Run only library tests
cargo test --lib

# Run only integration tests
cargo test --tests

# Run specific test file
cargo test --test tests

# Run single test
cargo test test_name

# Run with output
cargo test -- --nocapture test_name

# Run integration tests only
cargo test --test integration_tests

# Run with nextest (if installed)
cargo install cargo-nextest
cargo nextest run

Code Quality

# Check compilation errors
cargo check

# Format code
cargo fmt

# Format check (CI compatible)
cargo fmt --check

# Lint code
cargo clippy

# Lint with all warnings treated as errors
cargo clippy -- -W warnings

# Run security audit
cargo audit

Pre-commit Hooks

# One-time setup
./scripts/setup-pre-commit.sh

# Run on all files
pre-commit run --all-files

# Run on specific files
pre-commit run --files src/main.rs

# Update hooks
pre-commit autoupdate

# Uninstall hooks
pre-commit uninstall

Version Management and Release

Complete Release Workflow (Recommended):

./scripts/release.sh

This handles version increment, commit, and publish automatically.

Manual Workflow:

# 1. Make changes
git add .
git commit -m "Your message"

# 2. Increment version
./scripts/increment-version.sh

# 3. Run tests
cargo test

# 4. Publish to crates.io
./scripts/publish.sh

Version Format: Semantic versioning (x.y.z)

Major (x): Breaking changes
Minor (y): New features
Patch (z): Bug fixes

Dependency Management

# Update dependencies
cargo update

# Check outdated dependencies
cargo outdated

# Add new dependency
cargo add dependency_name

# Add development dependency
cargo add --dev dependency_name

# Remove dependency
cargo remove dependency_name

Project Structure

cc-switch/
├── src/
│   ├── lib.rs                 # Library crate with public API
│   ├── main.rs                # Minimal binary entry point
│   ├── cli/                   # CLI domain
│   │   ├── cli.rs             # Command-line interface definitions
│   │   ├── completion.rs      # Shell completion logic
│   │   ├── display_utils.rs   # Terminal display utilities
│   │   └── main.rs            # CLI command handlers
│   ├── config/                # Configuration domain
│   │   ├── mod.rs             # Module exports
│   │   ├── config.rs          # Configuration management
│   │   ├── config_storage.rs  # Persistent storage
│   │   └── types.rs           # Data structures
│   ├── interactive/           # Interactive UI domain
│   │   ├── mod.rs             # Module exports
│   │   └── interactive.rs     # Terminal UI with keyboard navigation
│   ├── claude_settings.rs     # Claude settings.json management
│   └── utils.rs               # Utility functions
├── tests/                     # Integration tests (not unit tests)
│   ├── integration_tests.rs   # End-to-end workflows
│   ├── main_tests.rs          # CLI main logic tests
│   ├── tests.rs               # Core functionality tests
│   ├── completion_tests.rs    # Shell completion tests
│   ├── interactive_tests.rs   # Interactive UI tests
│   └── error_handling_tests.rs # Error scenarios
├── scripts/                   # Automation scripts
│   ├── release.sh             # Full release workflow
│   ├── increment-version.sh   # Version bumping
│   ├── publish.sh             # Publish to crates.io
│   └── setup-pre-commit.sh    # Pre-commit setup
└── .github/workflows/         # CI/CD pipelines
    ├── ci.yml                 # Multi-platform CI
    └── release.yml            # Release automation

Architecture Overview

Library + Binary Structure

The project is structured as a library crate with a minimal binary entry point:

src/lib.rs: Declares the library crate with public API exports
src/main.rs: Binary that calls cc_switch::run() from the library
Benefits: Enables code reuse, better testing, can be imported by other projects

Domain-Based Organization

The codebase is organized into three main domains:

1. CLI Domain (`src/cli/`)

Purpose: Command-line interface, parsing, shell integration Key Components:

cli.rs: clap-based command parser, Commands enum
completion.rs: Shell completion script generation (fish, zsh, bash, elvish, powershell)
main.rs: Command handlers (add, remove, list, completion, etc.)
display_utils.rs: Terminal text formatting, width calculation, alignment

2. Configuration Domain (`src/config/`)

Purpose: Configuration management, persistence, validation Key Components:

types.rs: Data structures (Configuration, ConfigStorage, ClaudeSettings)
config.rs: Environment variable management
config_storage.rs: JSON persistence to ~/.cc-switch/configurations.json
Exports convenience functions: validate_alias_name(), get_config_storage_path()

3. Interactive Domain (`src/interactive/`)

Purpose: Terminal-based interactive UI Key Components:

interactive.rs: Crossterm-based terminal UI
handle_current_command(): Main interactive menu
handle_interactive_selection(): Configuration browser with preview
Features: Number key selection (1-9), smart pagination, keyboard navigation, auto-launch Claude

Data Flow

Add Configuration → CLI parses args → Validates → Saves to JSON via ConfigStorage
Switch Configuration → Interactive mode → Reads config → Updates Claude settings.json → Launches Claude
List Configurations → Reads from ConfigStorage → Displays (JSON or plain text)
Shell Completion → Dynamically loads configuration names → Generates shell-specific scripts

Key Data Types

Configuration (in src/config/types.rs):

struct Configuration {
    alias_name: String,
    token: String,
    url: String,
    model: Option<String>,
    small_fast_model: Option<String>,
    max_thinking_tokens: Option<u32>,
    api_timeout_ms: Option<u32>,
    claude_code_disable_nonessential_traffic: Option<u32>,
    anthropic_default_sonnet_model: Option<String>,
    anthropic_default_opus_model: Option<String>,
    anthropic_default_haiku_model: Option<String>,
}

ConfigStorage:

Manages multiple Configuration objects
Persists to ~/.cc-switch/configurations.json
Provides CRUD operations

EnvironmentConfig:

Converts Configuration to environment variable tuples
Used for launching Claude with custom settings

CLI Usage Patterns

# Add configurations
cc-switch add my-config sk-ant-xxx https://api.anthropic.com
cc-switch add my-config -t sk-ant-xxx -u https://api.anthropic.com
cc-switch add my-config -t sk-ant-xxx -u https://api.anthropic.com -m claude-3-5-sonnet-20241022
cc-switch add my-config -i  # Interactive mode
cc-switch add my-config --from-file config.json  # Import from JSON

# Switch configurations
# Interactive mode to view and switch configurations
cc-switch  # Enter interactive mode (no arguments needed)

# List configurations
cc-switch list  # JSON output (default)
cc-switch list -p  # Plain text output

# Current configuration with interactive menu
cc-switch current  # Shows current + allows switching

# Manage configurations
cc-switch remove config1 config2 config3

# Shell integration
cc-switch completion fish  # Generate completion script

Interactive Features

Interactive Configuration Selection (`cc-switch`)

Navigation:

↑↓: Navigate menu
1-9: Quick-select configuration on current page
N/PageDown: Next page (when >9 configs)
P/PageUp: Previous page
R: Reset to official Claude (removes custom settings)
E: Exit
Enter: Confirm selection

Features:

Real-time configuration preview
Smart pagination (9 configs per page)
Graceful terminal fallback
Auto-launches Claude after switch

Keyboard Shortcuts

Single Page (≤9 configs): 1-9 keys select directly Multi Page (>9 configs): 1-9 keys select on current page, use N/P to navigate

Shell Integration

Setup Completion

Fish:

cargo run -- completion fish > ~/.config/fish/completions/cc-switch.fish

Zsh:

cargo run -- completion zsh > ~/.zsh/completions/_cc-switch
echo 'fpath=(~/.zsh/completions $fpath)' >> ~/.zshrc

Bash:

cargo run -- completion bash > ~/.bash_completion.d/cc-switch
echo 'source ~/.bash_completion.d/cc-switch' >> ~/.bashrc

Aliases

You can add your own shell aliases for quick access:

# Fish
echo "alias cs='cc-switch'" >> ~/.config/fish/config.fish
echo "alias ccd='claude --dangerously-skip-permissions'" >> ~/.config/fish/config.fish

# Zsh
echo "alias cs='cc-switch'" >> ~/.zshrc
echo "alias ccd='claude --dangerously-skip-permissions'" >> ~/.zshrc

# Bash
echo "alias cs='cc-switch'" >> ~/.bashrc
echo "alias ccd='claude --dangerously-skip-permissions'" >> ~/.bashrc

Testing Strategy

Test Organization

Library Tests (#[cfg(test)] in src/): 20 tests
- Unit tests for individual functions
- Tests in same file as code
Integration Tests (tests/ directory): 154 tests
- End-to-end workflow testing
- CLI interaction testing
- Error handling and edge cases
- Cross-platform compatibility

Running Tests

# All tests
cargo test

# Library only
cargo test --lib

# Integration only
cargo test --tests

# Specific integration test
cargo test --test integration_tests

# Single test
cargo test test_name

# With output
cargo test -- --nocapture

Test Coverage

Configuration Management: CRUD operations, validation, JSON serialization
Settings Management: Environment variable handling, JSON persistence
CLI Parsing: Command structure, argument validation, help generation
Error Handling: Invalid inputs, file operations, edge cases
Interactive Features: Keyboard navigation, pagination, boundary conditions
Shell Integration: Completion generation, alias output
Cross-Platform: Path resolution, file operations on different OSes

Pre-commit Hooks

Automatic Checks (run on every commit):

cargo check - Compilation verification
cargo fmt --check - Code formatting
cargo clippy -- -D warnings - Linting (warnings as errors)
cargo test - All tests
cargo audit - Security vulnerability scan
cargo doc --no-deps - Documentation build

Setup: ./scripts/setup-pre-commit.sh

CI/CD Pipeline

CI Workflow (`.github/workflows/ci.yml`)

Multi-platform: Ubuntu, Windows, macOS
Cross-compilation: x86_64 and aarch64
Runs: formatting check, clippy, tests, security audit
Coverage reporting with codecov

Release Workflow (`.github/workflows/release.yml`)

Multi-architecture releases (Linux, Windows, macOS Intel/ARM)
Automatic tar.gz packaging
GitHub release creation with changelog
brew repo addr https://github.com/Linuxdazhao/homebrew-cc-switch/tree/main

File Storage Locations

Configuration Storage: ~/.cc-switch/configurations.json
Claude Settings: ~/.claude/settings.json (default) or custom via --set-default-dir
Path Resolution: Supports absolute and home-relative paths

Error Handling

Uses anyhow for error context and propagation
All operations include detailed error messages
Graceful handling of missing files (creates defaults)
Validates inputs before processing

Cross-Platform Support

Uses dirs crate for home/config directory resolution
Handles path differences (Windows, Linux, macOS)
CI builds for multiple target architectures
Terminal handling via crossterm (cross-platform)

Common Development Tasks

Adding a New Command

Add variant to Commands enum in src/cli/cli.rs
Implement handler in src/cli/main.rs
Add match arm in run() function
Add completion support in src/cli/completion.rs if needed
Write integration tests in tests/
Update help text in src/cli/cli.rs

Modifying Configuration Structure

Update Configuration struct in src/config/types.rs
Update serialization in config_storage.rs if needed
Update validation in src/config/config.rs
Update tests to reflect changes
Test backward compatibility

Adding Shell Support

Add shell variant in src/cli/completion.rs::generate_completion()
Add completion logic for the shell
Add to generate_aliases() if needed
Update help text
Test on actual shell

Important Implementation Notes

Security

API tokens are never logged
Sensitive input handled carefully in interactive mode
Configuration files should have appropriate permissions

Backward Compatibility

Existing configuration files remain compatible
Uses interactive mode for configuration switching

Performance

Configuration loading is lazy (only when needed)
Large configuration lists paginated for responsiveness
Release build optimized with LTO and size optimization

Key Dependencies

anyhow: Context-rich error handling
clap: CLI parsing with derive macros
clap_complete: Shell completion generation
serde/serde_json: JSON serialization
dirs: Cross-platform directory paths
colored: Terminal output formatting
crossterm: Terminal manipulation and events
tempfile: Testing with temporary files

Version and Compatibility

Rust Version: 1.88.0 or later
Rust Edition: 2024
Platforms: Linux, macOS, Windows (CI tested)
Architectures: x86_64, aarch64 (via CI)

Before Pushing to GitHub

Verify locally:

cargo test              # All tests pass
cargo clippy -- -W warnings  # No warnings
cargo fmt --check       # Code formatted
cargo audit            # No security vulnerabilities

These are automatically checked by CI, but catching issues locally saves time.

FilesExpand file tree

CLAUDE.md

Latest commit

History

CLAUDE.md

File metadata and controls

CLAUDE.md

Project Overview

Development Commands

Build and Run

Testing

Code Quality

Pre-commit Hooks

Version Management and Release

Dependency Management

Project Structure

Architecture Overview

Library + Binary Structure

Domain-Based Organization

1. CLI Domain (src/cli/)

2. Configuration Domain (src/config/)

3. Interactive Domain (src/interactive/)

Data Flow

Key Data Types

CLI Usage Patterns

Interactive Features

Interactive Configuration Selection (cc-switch)

Keyboard Shortcuts

Shell Integration

Setup Completion

Aliases

Testing Strategy

Test Organization

Running Tests

Test Coverage

Pre-commit Hooks

CI/CD Pipeline

CI Workflow (.github/workflows/ci.yml)

Release Workflow (.github/workflows/release.yml)

File Storage Locations

Error Handling

Cross-Platform Support

Common Development Tasks

Adding a New Command

Modifying Configuration Structure

Adding Shell Support

Important Implementation Notes

Security

Backward Compatibility

Performance

Key Dependencies

Version and Compatibility

Before Pushing to GitHub

1. CLI Domain (`src/cli/`)

2. Configuration Domain (`src/config/`)

3. Interactive Domain (`src/interactive/`)

Interactive Configuration Selection (`cc-switch`)

CI Workflow (`.github/workflows/ci.yml`)

Release Workflow (`.github/workflows/release.yml`)