ccuse: A Profile Switcher for Claude Code CLI

This repository contains ccuse, a command-line profile switcher designed for the Claude Code CLI. The tool enables developers to switch between native Claude Code account/subscription mode and compatible API providers across three configuration scopes: globally, per project, or for a single temporary shell session.

What ccuse Provides

According to the repository documentation, ccuse addresses a specific need for developers using Claude Code with multiple AI API providers. Instead of manually editing configuration files or managing multiple sets of environment variables each time you want to use a different model provider, ccuse creates, stores, and activates profiles through simple shell commands.

The documented functionality supports five API provider profiles:

1. Claude (Native) - Uses the Claude Code account/subscription or Anthropic API directly
2. Volcengine Ark - Uses the Volcengine Ark Agent Plan
3. GLM via Ark Agent Plan - Uses GLM models through the Volcengine Ark Agent Plan
4. Kimi - Uses Moonshot AI's Kimi API
5. MiniMax - Uses the MiniMax API

Each profile corresponds to specific models. For example, the Volcengine Ark profile supports doubao-seed-2-0-code-preview-260215, GLM profiles support GLM-5.1, GLM-4.7, and GLM-4.7-FlashX, Kimi profiles support kimi-k2.6, and MiniMax profiles support MiniMax-M2.7 and MiniMax-M2.7-highspeed. Context windows for these models range up to 256K, based on each provider's documented specifications.

Three Configuration Scopes

One of the key design features described in the documentation is the ability to apply profiles at three different scopes, each with different persistence characteristics.

Global Scope

Global profile switching modifies the main Claude Code settings.json file. When activated, the selected profile becomes the default for all Claude Code instances launched anywhere on the system. The tool automatically creates a backup of the current settings file before switching profiles.

Commands at this scope include:

• ccuse claude or ccuse global claude - Switch to native Claude profile
• ccuse ark or ccuse global ark - Switch to Volcengine Ark profile
• ccuse glm or ccuse global glm - Switch to GLM profile
• ccuse kimi or ccuse global kimi - Switch to Kimi profile
• ccuse minimax or ccuse global minimax - Switch to MiniMax profile

Project Scope

Project-scoped profiles allow a specific repository or working directory to use a different provider than the global default. This is useful when working on multiple projects that have different model requirements or when you want to isolate testing of a particular provider without affecting your global default configuration.

Project scope creates a ./.claude/settings.json file in the current working directory, leaving the global ~/.claude/settings.json file untouched. Claude Code automatically reads project-level configuration when launched from that directory.

Commands include:

• ccuse project <profile> - Persist profile for current project
• ccuse project show - Display current project profile
• ccuse project rm - Remove project-specific profile

Session Scope

Session-level switching operates entirely through environment variables and makes no permanent file changes. This is useful for one-off testing or when you want to temporarily try a different provider without changing any persistent configuration.

When using eval "$(ccuse local <profile>)", the profile's environment variables are loaded into the current shell session. The ccuse start <profile> command loads the environment variables and immediately launches Claude Code.

Quick-start shortcuts are also provided:

• ccuse cc - Claude profile + launch
• ccuse ca - Ark profile + launch
• ccuse ck - Kimi profile + launch
• ccuse cg - GLM profile + launch
• ccuse cm - MiniMax profile + launch

The -c or --continue flag can be added to resume the last Claude Code conversation.

Profile Management Features

Beyond switching profiles, the tool includes several profile management commands:

• ccuse init-<provider> - Creates or reconfigures a profile template
• ccuse list - Lists all available profiles and marks the active one
• ccuse show - Shows current Claude Code configuration with secrets masked
• ccuse doctor - Checks setup, active scopes, and suggests next steps
• ccuse edit <name> - Opens a profile file for editing
• ccuse remove <name> - Removes a profile after confirmation

The ccuse doctor command is described as particularly useful for first-time users or when troubleshooting, as it checks whether Claude Code, Python, profiles, and project settings are properly configured.

Installation Methods

Three installation approaches are documented:

1. One-Line Install (Recommended): Downloads the script directly to ~/.local/bin/ccuse and makes it executable
2. Install via Claude Code Skill: Can be installed by asking Claude Code directly
3. Manual Install: Involves cloning the repository and creating a symlink to the executable

After installation, ccuse --help verifies that the tool is working correctly.

Profile Setup Workflow

The documented workflow for setting up profiles follows five steps:

1. Check setup with ccuse doctor to verify prerequisites
2. Save current Claude settings with ccuse init-claude to create a native Claude profile
3. Create additional profiles using commands like ccuse init-ark, ccuse init-glm, ccuse init-kimi, or ccuse init-minimax
4. Set API keys by editing the profile files that are automatically opened
5. Choose the scope for each profile: one-time session, project-specific, or global

When creating profiles, the init commands automatically open the profile file for editing using the user's preferred editor (following the order: $EDITOR environment variable, VS Code code, then nano).

Custom Profiles

The documentation indicates that developers can create custom profiles for any Anthropic-compatible API. Custom profiles are stored as JSON files in ~/.claude/profiles/ and can contain configuration for API keys, base URLs, timeout settings, and other environment variables.

Profile naming rules are specified: names must start with a letter or number and may contain letters, numbers, dots, underscores, and hyphens. Certain names are reserved and cannot be used for custom profiles, including built-in commands and aliases.

File Structure

The tool stores profiles and configuration in the following directory structure under ~/.claude/:

• settings.json - Active global configuration
• settings.json.bak - Automatic backup
• profiles/ - Directory containing individual profile JSON files

Several environment variables are available to customize these paths, including CLAUDE_DIR, PROFILE_DIR, SETTINGS_FILE, BACKUP_SUFFIX, PROJECT_CLAUDE_DIR, and PROJECT_SETTINGS_FILE.

Testing

The repository includes a comprehensive test suite using bats-core (Bash Automated Testing System). Tests can be run after installing bats with bats tests/test_ccuse.bats.

Interpretation and Use Cases

Based on the documented functionality, this tool appears most useful for developers who regularly use Claude Code and want to experiment with multiple AI API providers without manual configuration overhead. The three scopes (global, project, session) provide flexibility matching different workflows.

Developers working across multiple projects with different model requirements may find the project-scoped profiles particularly useful, allowing each repository to maintain its own default provider without affecting the global configuration. Similarly, the session-level switching is well-suited for side-by-side testing of different providers on the same tasks.

The ability to create custom profiles also means the tool is not limited to the five pre-configured providers, potentially extending its utility to any API endpoint with Anthropic-compatible authentication.

Sources

• Repository: https://github.com/kevinten-ai/ccuse
• Verified commit: https://github.com/kevinten-ai/ccuse/commit/07adde051c787b6e3bb3585ace9a2a6080ebd7f9