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.

Name		Name	Last commit message	Last commit date
Latest commit History 55 Commits
.github		.github
cmd		cmd
completion		completion
docs		docs
internal		internal
.gitignore		.gitignore
.goreleaser.yml		.goreleaser.yml
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
INSTALL.md		INSTALL.md
LICENSE		LICENSE
Makefile		Makefile
PHASE1_COMPLETE.md		PHASE1_COMPLETE.md
PHASE2_COMPLETE.md		PHASE2_COMPLETE.md
PHASE3_COMPLETE.md		PHASE3_COMPLETE.md
PHASE4_COMPLETE.md		PHASE4_COMPLETE.md
README.md		README.md
SECURITY.md		SECURITY.md
go.mod		go.mod
go.sum		go.sum
main.go		main.go
prompt.md		prompt.md

Folders and files

Latest commit

History

Repository files navigation

claudectx

Why claudectx?

Why Developers Choose claudectx

Who Benefits Most

What is claudectx?

Quick Start

Interactive Mode

Direct Switch

Run a Single Session Without Switching

Toggle Between Profiles

Installation

macOS / Linux (Homebrew)

Manual Installation

Complete Usage Guide

Managing Profiles

Session Launcher (Run)

Advanced Features

Real-World Examples

Freelancer Managing Multiple Clients

Developer with Work and Personal Accounts

Team Sharing Configuration

Example Configurations

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

Creating a Profile with MCP Servers

Creating a Profile for AWS Bedrock

Creating a Profile with Custom CLAUDE.md Instructions

Quick Profile Creation Workflow

Switch vs Run

What Gets Switched?

Safety Features

Shell Completion

Troubleshooting

"command not found: claudectx"

"profile does not exist"

Accidentally deleted a profile

Settings aren't taking effect

How It Works

Get Help

Comparison with Other Tools

License

Credits

About

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 9

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages