ClaudeCodeInstanceManager 1.0.0

Claude Code Instance Manager (ccim)

A powerful CLI tool for managing multiple Claude Code configurations. Create, manage, and switch between isolated Claude Code instances with distinct API endpoints, credentials, and permission settings.

Why Use Claude Code Instance Manager?

When working with Claude Code across different projects, environments, or API providers, you often need to manage separate configurations:

• Multiple API Providers: Switch between Anthropic direct API, AWS Bedrock, Google Vertex AI, or custom endpoints
• Environment Isolation: Keep work and personal configurations separate
• Team Settings: Maintain different permission sets for various project requirements
• Testing: Test configurations without affecting your primary setup

Features

• Instance Management: Create, list, remove, and sync Claude Code instances
• Configuration Control: Set, get, and manage environment variables per instance
• Shell Integration: Generate shell functions for PowerShell, Bash, and Zsh
• Cross-Platform: Works on Windows, macOS, and Linux
• Secure: Automatic masking of sensitive data (API keys, tokens)
• Backup Protection: Automatic backups before destructive operations

Installation

Prerequisites

• .NET 8.0 SDK or later
• Claude Code CLI installed

Install via NuGet (Recommended)

dotnet tool install --global ClaudeCodeInstanceManager

Update to Latest Version

dotnet tool update --global ClaudeCodeInstanceManager

Uninstall

dotnet tool uninstall --global ClaudeCodeInstanceManager

Quick Start

1. Create a New Instance

# Create instance by cloning default configuration
ccim create work

# Create instance from another instance
ccim create bedrock --source work

# Create empty instance
ccim create testing --empty

2. Configure the Instance

# Set API endpoint
ccim config set work ANTHROPIC_BASE_URL https://api.example.com

# Set API key
ccim config set work ANTHROPIC_API_KEY sk-ant-your-key

# Enable AWS Bedrock
ccim config set bedrock CLAUDE_CODE_USE_BEDROCK 1

3. Generate Shell Functions

# Generate functions for your shell
ccim shell

# Output directly to shell profile
ccim shell --output ~/.bashrc --append

4. Use Your Instance

# After sourcing shell functions
claude-work   # Uses 'work' instance
claude-bedrock # Uses 'bedrock' instance
claude-default # Resets to default

Command Reference

Global Options

Option	Description
-v, --verbose	Enable verbose output
--no-color	Disable colored output
-h, --help	Show help information
--version	Show version information

---

ccim create

Create a new Claude Code instance by cloning an existing configuration.

ccim create <name> [options]

Argument/Option	Description
<name>	Name for the new instance (e.g., 'work', 'bedrock')
-s, --source <NAME>	Source instance to clone from (default: 'default')
-f, --force	Overwrite existing instance
--empty	Create an empty instance instead of cloning

Examples:

ccim create production
ccim create staging --source production
ccim create test --empty
ccim create dev --force

---

ccim list (alias: ls)

List all available Claude Code instances.

ccim list [options]

Option	Description
-l, --long	Show detailed information
--json	Output as JSON

Examples:

ccim list
ccim list -l
ccim list --json

Sample Output:

Claude Code Instances

 * work
   production
   default               (default)

Use 'ccim list -l' for detailed information.

---

ccim remove (aliases: rm, delete)

Remove a Claude Code instance.

ccim remove <name> [options]

Argument/Option	Description
<name>	Instance name to remove
-f, --force	Skip confirmation prompt
--no-backup	Don't create backup before removing

Examples:

ccim remove old-instance
ccim remove test --force
ccim remove staging --no-backup

---

ccim which (alias: current)

Show which Claude Code instance is currently active.

ccim which [options]

Option	Description
-v, --verbose	Show detailed information about the current instance

Examples:

ccim which
ccim which -v

---

ccim sync

Sync commands, agents, or settings from one instance to another.

ccim sync <source> <target> [options]

Argument/Option	Description
<source>	Source instance name
<target>	Target instance name
--commands	Sync custom commands (default: true)
--agents	Sync custom agents (default: true)
--settings	Sync settings.json (default: false)
--all	Sync everything (commands, agents, settings)
-f, --force	Overwrite existing files
-n, --dry-run	Show what would be synced without making changes

Examples:

ccim sync default work
ccim sync production staging --settings
ccim sync default work --all --force
ccim sync work production --dry-run

---

ccim shell

Generate shell functions for launching Claude Code instances.

ccim shell [options]

Option	Description
-s, --shell <SHELL>	Target shell: powershell, pwsh, bash, zsh
-o, --output <PATH>	Output to file instead of stdout
--append	Append to file instead of overwriting

Examples:

ccim shell
ccim shell --shell bash
ccim shell --output ~/.bashrc --append
ccim shell --shell powershell --output $PROFILE

Generated Functions:

Function	Description
claude-<instance>	Launch Claude with the specified instance configuration
claude-which	Show current Claude configuration
claude-default	Reset to default configuration

---

ccim config

Manage instance configuration settings.

ccim config set

Set an environment variable in an instance's settings.

ccim config set <instance> <key> <value>

Examples:

ccim config set work ANTHROPIC_BASE_URL https://api.anthropic.com
ccim config set work ANTHROPIC_API_KEY sk-ant-api03-xxx
ccim config set bedrock CLAUDE_CODE_USE_BEDROCK 1

ccim config get

Get an environment variable from an instance's settings.

ccim config get <instance> <key>

Examples:

ccim config get work ANTHROPIC_BASE_URL
ccim config get bedrock CLAUDE_CODE_USE_BEDROCK

ccim config unset

Remove an environment variable from an instance's settings.

ccim config unset <instance> <key>

Examples:

ccim config unset work ANTHROPIC_MODEL

ccim config show

Show all configuration for an instance.

ccim config show <instance> [options]

Option	Description
--show-secrets	Show sensitive values (keys, tokens) in plain text
--json	Output as JSON

Examples:

ccim config show work
ccim config show production --show-secrets
ccim config show staging --json

ccim config env

List available Claude Code environment variables and their descriptions.

ccim config env

---

Environment Variables Reference

Variable	Description
ANTHROPIC_API_KEY	Direct API key authentication (sk-ant-...)
ANTHROPIC_AUTH_TOKEN	Bearer token authentication
ANTHROPIC_BASE_URL	Custom API endpoint URL
ANTHROPIC_MODEL	Default model selection (e.g., claude-sonnet-4-5-20250929)
API_TIMEOUT_MS	Request timeout in milliseconds
CLAUDE_CODE_USE_BEDROCK	Enable AWS Bedrock integration (set to '1')
CLAUDE_CODE_USE_VERTEX	Enable Google Vertex AI (set to '1')

Configuration Storage

Instances are stored in your home directory:

Instance	Path
Default	~/.claude/
Named	~/.claude-<name>/

Each instance contains:

~/.claude-<name>/
├── settings.json      # Environment variables and permissions
├── commands/          # Custom slash commands (*.md)
└── agents/            # Custom agents (*.md)

Use Cases

Enterprise API Gateway

Configure Claude Code to use your organization's API gateway:

ccim create enterprise
ccim config set enterprise ANTHROPIC_BASE_URL https://api.corp.example.com
ccim config set enterprise ANTHROPIC_AUTH_TOKEN your-sso-token

AWS Bedrock Integration

Set up Claude Code with AWS Bedrock:

ccim create bedrock
ccim config set bedrock CLAUDE_CODE_USE_BEDROCK 1
ccim config set bedrock AWS_REGION us-east-1

Google Vertex AI

Configure for Vertex AI:

ccim create vertex
ccim config set vertex CLAUDE_CODE_USE_VERTEX 1
ccim config set vertex GOOGLE_CLOUD_PROJECT your-project-id

Development vs Production

Maintain separate configurations:

ccim create dev
ccim create staging --source dev
ccim create production --source staging

Exit Codes

Code	Description
0	Success
1	Invalid arguments
2	Instance not found
3	Instance already exists
4	Source not found
5	Configuration error
6	File operation error
10	Operation cancelled
99	Unknown error

Security Considerations

• Credential Storage: API keys are stored in plaintext in settings.json. Ensure proper file permissions.
• Automatic Masking: The CLI automatically masks sensitive values when displaying configurations.
• Backup Files: Backups created before removal may contain sensitive data.

Recommended Permissions

# Linux/macOS
chmod 700 ~/.claude-*
chmod 600 ~/.claude-*/settings.json

Troubleshooting

Instance Not Found

Ensure the instance exists:

ccim list

Shell Functions Not Working

1. Regenerate shell functions: ccim shell
2. Source your profile: . ~/.bashrc or . $PROFILE
3. Verify Claude Code is in PATH: which claude

Configuration Not Applied

Check the active instance:

ccim which -v
echo $CLAUDE_CONFIG_DIR  # Unix
echo $env:CLAUDE_CONFIG_DIR  # PowerShell

Building from Source

git clone https://github.com/ShadyNagy/ClaudeCodeInstanceManager.git
cd ClaudeCodeInstanceManager
dotnet build
dotnet pack
dotnet tool install --global --add-source ./src/ClaudeCodeInstanceManager/nupkg ClaudeCodeInstanceManager

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

ShadyNagy

• GitHub: @ShadyNagy
• Project: ClaudeCodeInstanceManager

Acknowledgments

• Claude Code by Anthropic
• McMaster.Extensions.CommandLineUtils for CLI framework