claudectx

Stop editing config files. Start switching in seconds.

---

Why claudectx?

The Problem: You're juggling multiple Claude Code setups—work account, personal projects, different API providers, client-specific instructions. Every time you need to switch, you're manually editing settings.json, swapping CLAUDE.md files, and hoping you don't break something.

The Solution: claudectx lets you switch your entire Claude Code configuration with a single command. No more file editing. No more mistakes. Just type claudectx work and you're done.

# Before: Edit files, copy settings, pray nothing breaks
vim ~/.claude/settings.json  # 😰

# After: One command, instant switch
claudectx work  # ✅

Why Developers Choose claudectx

Pain Point	How claudectx Helps
"I keep overwriting my settings"	Automatic backups before every switch
"Switching takes 5+ minutes"	Switch in under 1 second
"I broke my config and lost work"	Instant rollback if anything fails
"I have 4 different API providers"	Unlimited profiles, easy toggle
"My team needs the same setup"	Export/import profiles as JSON
"I need work and personal open at the same time"	claudectx run launches per-session without touching global config

Who Benefits Most

• Consultants & Freelancers — Switch between client configs instantly
• Teams — Share standardized profiles across developers
• Power Users — Test different models, API providers, and MCP servers
• Anyone who's tired of manual configuration management

---

What is claudectx?

claudectx is a command-line tool that lets you quickly switch between different Claude Code configurations. Think of it like profiles for your browser, but for Claude Code.

Perfect for:

• 👔 Switching between work and personal Claude accounts
• 🏢 Managing different client configurations
• 🔌 Testing different API providers (Anthropic, Bedrock, OpenRouter, Z.AI, custom endpoints)
• 🛠️ Using different tool permissions and MCP servers
• 📝 Maintaining separate instruction sets (CLAUDE.md files)

---

Quick Start

Interactive Mode

The easiest way to switch profiles:

claudectx

Use ↑/↓ arrow keys to navigate, Enter to select:

Select a profile:

  work
❯ personal (current)
  client-acme

Use ↑/↓ to navigate, Enter to select, Esc/Ctrl+C to cancel

Direct Switch

If you know the profile name:

claudectx work

Run a Single Session Without Switching

Open a Claude session using a profile without changing your global config.
Useful when you want work and personal sessions open at the same time:

claudectx run work

Pass extra Claude flags after --:

claudectx run work -- --model opus
claudectx run review -- -p "Review this diff"

Preview the command without launching:

claudectx run work --dry-run

See Switch vs Run for a full comparison.

Toggle Between Profiles

Quickly switch back and forth:

claudectx -

---

Installation

macOS / Linux (Homebrew)

brew install foxj77/tap/claudectx

This will install claudectx and shell completions automatically.

Manual Installation

Option 1: Install to your user directory (no sudo required)

cd ~/Downloads
git clone https://github.com/foxj77/claudectx.git
cd claudectx
make install-user

This installs to ~/go/bin/claudectx. Make sure ~/go/bin is in your PATH:

# For bash
echo 'export PATH="$PATH:~/go/bin"' >> ~/.bashrc
source ~/.bashrc

# For zsh
echo 'export PATH="$PATH:~/go/bin"' >> ~/.zshrc
source ~/.zshrc

Option 2: Install system-wide

cd ~/Downloads
git clone https://github.com/foxj77/claudectx.git
cd claudectx
sudo make install

This installs to /usr/local/bin/claudectx.

Option 3: Download pre-built binary

Download pre-built binaries for your platform from the releases page.

Available for:

• macOS (Intel and Apple Silicon)
• Linux (x64 and ARM64)
• Windows (x64)

---

Complete Usage Guide

Managing Profiles

Create a new profile from your current settings:

claudectx -n work

List all profiles (simple text output):

claudectx -l

Show current profile:

claudectx -c

Delete a profile:

claudectx -d old-client

Session Launcher (Run)

claudectx run starts Claude Code with a profile's settings for the current terminal session only. No global state is modified — your active settings.json, CLAUDE.md, MCP servers, and current/previous profile trackers are all left untouched.

# Basic: launch Claude with 'work' profile in this terminal
claudectx run work

# Pass Claude flags after --
claudectx run work -- --model opus --permission-mode plan

# Non-interactive: run a prompt and exit
claudectx run review -- -p "Summarise this PR" --output-format text

# Dry-run: print the command without executing
claudectx run work --dry-run

How it works:

Profile component	Mechanism
Settings (model, env, permissions)	--settings <profile/settings.json>
CLAUDE.md instructions	--append-system-prompt-file <profile/CLAUDE.md>
MCP servers	Generated --mcp-config temp file + --strict-mcp-config

Important caveats:

• Settings: Profile scalar settings (model, env vars, permission mode) override global ~/.claude/settings.json. Permission arrays (allow/deny) are merged — a profile cannot narrow permissions already granted globally.
• CLAUDE.md: The profile's CLAUDE.md is appended to the session system prompt. It is not a full replacement — your global ~/.claude/CLAUDE.md remains active alongside it.
• MCP: Only the profile's MCP servers are used (--strict-mcp-config). Global MCP servers from ~/.claude.json are excluded for that session.
• Auth: Authentication is not profile-scoped. run uses whatever Claude Code login is currently active.
• In-session changes: /config edits inside a run session write to the normal user config, not the profile's settings.json.

Advanced Features

Export a profile to share with teammates:

# Export to file
claudectx export work work-profile.json

# Export to stdout (for piping)
claudectx export work

Import a profile:

# Import from file
claudectx import work-profile.json

# Import and rename
claudectx import work-profile.json client-new

# Import from stdin
cat work-profile.json | claudectx import

Check profile health (validates settings):

# Check current profile
claudectx health

# Check specific profile
claudectx health work

Transfer profiles between machines:

claudectx export work | ssh remote-machine 'claudectx import - work'

---

Real-World Examples

Freelancer Managing Multiple Clients

# Create profiles for each client
claudectx -n client-acme
claudectx -n client-globex
claudectx -n personal

# Switch global config to a client
claudectx client-acme

# Or run two client sessions concurrently in separate terminals
claudectx run client-acme    # terminal 1
claudectx run client-globex  # terminal 2

# Quick toggle between client and personal
claudectx -

# Export client profile for backup
claudectx export client-acme ~/backups/acme-$(date +%Y%m%d).json

Developer with Work and Personal Accounts

# Create work profile
claudectx -n work

# Create personal profile
claudectx -n personal

# Start work day — switches global config
claudectx work

# End of day, switch to personal
claudectx personal

# Or use interactive mode
claudectx

# Need both open at once? Use run in separate terminals
claudectx run work      # terminal 1 — work session, global config unchanged
claudectx run personal  # terminal 2 — personal session, global config unchanged

Team Sharing Configuration

# Team lead creates and exports standard config
claudectx -n team-standard
claudectx export team-standard team-config.json

# Share file with team (email, Slack, git repo, etc.)

# Team members import
claudectx import team-config.json work

---

Example Configurations

Here are real-world profile configurations you can use as templates.

Creating a Profile for Alternative API Providers (e.g., GLM-4.7 via Z.AI)

First, configure your current Claude Code settings, then save them as a profile:

1. Edit your settings file (~/.claude/settings.json):

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "a1b2c3d4e5f6789012345678abcdef90.XyZ123AbCdEfGhIjKlMn",
    "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-4.5-air",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-4.7",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-4.7",
    "API_TIMEOUT_MS": "3000000"
  },
  "permissions": {}
}

2. Save it as a profile:

claudectx -n glm-provider

3. Switch to it anytime:

claudectx glm-provider

Creating a Profile with MCP Servers

If you use MCP (Model Context Protocol) servers, you can include them in profiles:

1. Your MCP configuration (~/.claude/profiles/devops/mcp.json):

{
  "flux-operator-mcp": {
    "type": "stdio",
    "command": "/opt/homebrew/bin/flux-operator-mcp",
    "args": ["serve"],
    "env": {
      "KUBECONFIG": "/Users/yourname/.kube/config"
    }
  }
}

2. Combined with settings (~/.claude/profiles/devops/settings.json):

{
  "env": {
    "KUBECONFIG": "/Users/yourname/.kube/config"
  },
  "permissions": {
    "allow": ["Bash(kubectl *)"]
  }
}

Creating a Profile for AWS Bedrock

{
  "env": {
    "ANTHROPIC_MODEL": "anthropic.claude-3-5-sonnet-20241022-v2:0",
    "AWS_REGION": "us-east-1",
    "AWS_PROFILE": "production",
    "CLAUDE_CODE_USE_BEDROCK": "1"
  },
  "permissions": {}
}

Save as a profile:

claudectx -n bedrock-prod

Creating a Profile with Custom CLAUDE.md Instructions

Each profile can have its own global instructions file:

1. Create your profile:

claudectx -n client-acme

2. Edit the profile's CLAUDE.md (~/.claude/profiles/client-acme/CLAUDE.md):

# ACME Corp Project Guidelines

- Always use TypeScript
- Follow ACME's coding standards
- Never commit directly to main
- Run tests before suggesting commits

When you switch to client-acme, this CLAUDE.md becomes your global instructions.

Quick Profile Creation Workflow

# 1. Configure Claude Code however you want (edit settings.json, CLAUDE.md, etc.)

# 2. Save current config as a new profile
claudectx -n my-new-profile

# 3. Verify it was created
claudectx -l

# 4. Switch away and back to test
claudectx -               # Toggle to previous
claudectx my-new-profile  # Switch back

---

Switch vs Run

claudectx has two ways to use a profile:

	claudectx <name>	claudectx run <name>
What it does	Permanently switches global config	Launches one Claude session with that profile
Modifies ~/.claude/settings.json	✅ Yes	❌ No
Modifies ~/.claude/CLAUDE.md	✅ Yes	❌ No
Modifies ~/.claude.json MCP servers	✅ Yes	❌ No
Updates current/previous tracker	✅ Yes	❌ No
Creates backup	✅ Yes	❌ No
Concurrent sessions	❌ No (last switch wins)	✅ Yes
Auto-syncs changes on next switch	✅ Yes	❌ No
CLAUDE.md semantics	Full replacement of global file	Appended to session prompt

Rule of thumb: use claudectx work when you want to change your default setup. Use claudectx run work when you need one session in a different context without disturbing anything else.

---

What Gets Switched?

When you run claudectx <name> (persistent switch), claudectx manages:

• ✅ ~/.claude/settings.json — All your Claude Code settings
• ✅ ~/.claude/CLAUDE.md — Your global instructions
• ✅ Model preferences (opus, sonnet, haiku)
• ✅ Environment variables
• ✅ Tool permissions
• ✅ MCP server configurations
• ✅ API configuration

What stays the same (both switch and run):

• ❌ Project-level settings in .claude/ folders
• ❌ OAuth session tokens
• ❌ Conversation history
• ❌ Project-specific configurations

---

Safety Features

claudectx is designed to be safe and reliable:

🛡️ Automatic Backups Every switch creates a timestamped backup in ~/.claude/backups/

🔍 Validation Profiles are validated before switching to prevent corruption

↩️ Automatic Rollback If anything goes wrong during a switch, your previous config is automatically restored

💾 Atomic Operations Settings files are updated atomically - no partial updates

🎨 Clear Feedback Color-coded output shows success (green), warnings (yellow), and errors (red)

---

Shell Completion

Enable tab completion for your shell:

Bash:

source /path/to/claudectx/completion/bash_completion.sh

Zsh:

# Copy to a directory in your $fpath
cp /path/to/claudectx/completion/zsh_completion.sh /usr/local/share/zsh/site-functions/_claudectx

Fish:

cp /path/to/claudectx/completion/fish_completion.fish ~/.config/fish/completions/

---

Troubleshooting

"command not found: claudectx"

Make sure the installation directory is in your PATH:

# Check if ~/go/bin is in PATH
echo $PATH | grep go/bin

# If not, add it:
echo 'export PATH="$PATH:~/go/bin"' >> ~/.zshrc  # or ~/.bashrc
source ~/.zshrc  # or source ~/.bashrc

"profile does not exist"

List available profiles to see what exists:

claudectx -l

Accidentally deleted a profile

Check your backups:

ls ~/.claude/backups/

Each backup directory contains a complete copy of your settings.

Settings aren't taking effect

Make sure Claude Code isn't running when you switch profiles. Restart Claude Code after switching.

---

How It Works

claudectx stores each profile in ~/.claude/profiles/:

~/.claude/
├── .claudectx-current          # Tracks which profile is active
├── .claudectx-previous         # Enables toggle with 'claudectx -'
├── .claudectx-run/             # Temp MCP configs for 'claudectx run' sessions
│   └── run-<timestamp>-<pid>/
│       └── mcp.json            # Auto-deleted when the session ends
├── profiles/
│   ├── work/
│   │   ├── settings.json
│   │   ├── CLAUDE.md
│   │   └── mcp.json
│   └── personal/
│       ├── settings.json
│       └── CLAUDE.md
├── backups/                    # Automatic backups (switch only)
│   └── backup-1234567890/
└── settings.json               # Active config

claudectx <name> (persistent switch): copies profile files to the active locations, creates a backup first, rolls back automatically on failure.

claudectx run <name> (session launch): passes --settings, --append-system-prompt-file, and a generated --mcp-config directly to claude. Nothing is copied or overwritten. The temp MCP config is deleted after Claude exits.

---

Get Help

View all commands:

claudectx --help

Check version:

claudectx --version

Found a bug? Open an issue on GitHub

---

Comparison with Other Tools

Feature	claudectx	cctx	Manual switching
Interactive selection	✅	❌	❌
Automatic backups	✅	❌	❌
Validation	✅	❌	❌
CLAUDE.md support	✅	❌	✅
Export/import	✅	❌	❌
Shell completion	✅	❌	❌
Health checks	✅	❌	❌
Rollback on error	✅	❌	❌
Concurrent sessions (run)	✅	❌	❌

---

License

MIT License - see LICENSE

---

Credits

Inspired by kubectx - the excellent Kubernetes context switcher.

Built by John Fox for the Claude Code community.