claude-toggle

A provider-agnostic utility for toggling between different Claude API providers in Claude Code. Switch seamlessly between Anthropic's official API, Z.AI GLM models, OpenAI-compatible endpoints, or self-hosted solutions.

Features

Provider-agnostic architecture - JSON-based configuration for easy provider management
Zero file modifications - All changes are scoped to the subprocess environment
Pass-through design - All Claude Code CLI options work transparently
Actionable error messages - Missing credentials trigger detailed setup instructions
Extensible - Add new providers by editing a single JSON file

Prerequisites

Bash (version 4.0+)
Python 3 (for JSON parsing, no external packages required)
Claude Code CLI installed and available as
```
claude
```

Installation

Option 1: npm (Recommended)

npm install -g @sekora_ai/claude-toggle

This works on macOS, Linux, and Windows (via WSL or Git Bash).

Option 2: Manual Installation

# Clone the repository
git clone https://gitlab.com/sekora-ai/claude-code/claude-toggle.git
cd claude-toggle
chmod +x claude-toggle

# Copy default config to user directory
mkdir -p ~/.config/claude-providers
cp providers.json ~/.config/claude-providers/

# Add to PATH (choose your shell)
# For bash:
echo 'export PATH="$HOME/path/to/claude-toggle:$PATH"' >> ~/.bashrc
source ~/.bashrc

# For zsh:
echo 'export PATH="$HOME/path/to/claude-toggle:$PATH"' >> ~/.zshrc
source ~/.zshrc

Usage

Basic Usage

# Launch with default provider (Anthropic)
./claude-toggle

# Launch with specific provider
./claude-toggle --provider glm

# List available providers
./claude-toggle --list-providers

# Validate provider configuration
./claude-toggle --validate --provider glm

Pass-through Options

All unrecognized options are forwarded to the Claude Code CLI:

# Pass options to Claude Code
./claude-toggle --provider glm --dangerously-skip-permissions

# Any Claude Code option works
./claude-toggle --provider anthropic --help

Command Reference

Option	Description
`-p, --provider <name>`	Select a specific provider
`-l, --list-providers`	List all available providers
`--validate`	Validate provider configuration without launching
`-v, --verbose`	Enable verbose output
`-h, --help`	Show help message
`--glm`	Legacy alias for `--provider glm`

Configuration

Configuration File Location

The script searches for

providers.json

in this order:

~/.config/claude-providers/providers.json

(recommended)

```
~/.claude-providers.json
```
```
<script-directory>/providers.json
```

Provider Configuration

Providers are configured in

providers.json

{
  "version": "1.0",
  "default_provider": "anthropic",
  "providers": {
    "anthropic": {
      "description": "Anthropic's official API",
      "enabled": true,
      "env_vars": {},
      "validation": {}
    },
    "glm": {
      "description": "Z.AI GLM models via proxy",
      "enabled": true,
      "env_vars": {
        "ANTHROPIC_AUTH_TOKEN": {
          "value": "${ZAI_API_KEY}",
          "required": true
        },
        "ANTHROPIC_BASE_URL": {
          "value": "https://api.z.ai/api/anthropic"
        }
      },
      "validation": {
        "required_env_vars": ["ZAI_API_KEY"]
      }
    }
  }
}

Adding New Providers

Interactive wizard (recommended):

If you're using Claude Code in this repository, run:

/add-provider

This walks you through the entire process interactively.

Manual configuration:

See PROVIDERS.md for detailed instructions on adding new providers.

Quick example:

"my-provider": {
  "description": "My custom provider",
  "enabled": true,
  "env_vars": {
    "ANTHROPIC_AUTH_TOKEN": {"value": "${MY_API_KEY}"},
    "ANTHROPIC_BASE_URL": {"value": "https://api.example.com/v1"}
  },
  "validation": {
    "required_env_vars": ["MY_API_KEY"]
  }
}

Built-in Providers

Provider	Description	Required Env Var
`anthropic`	Anthropic's official API (default)	None (uses default auth)
`glm`	Z.AI GLM models via proxy	`ZAI_API_KEY`

Examples

Using Z.AI GLM Provider

# Set your API key
export ZAI_API_KEY="your-key-here"

# Launch Claude Code with GLM
./claude-toggle --provider glm

Validating Before Launch

# Check if provider is properly configured
./claude-toggle --validate --provider glm

# Output: Provider 'glm' is valid and ready to use

Verbose Mode

# See which provider is being used
./claude-toggle --verbose --provider glm

# Output: Using provider: glm

CI/CD Setup (For Maintainers)

This project uses GitLab CI/CD to automatically publish to npm when version tags are pushed.

npm Token Setup

Important: As of December 9, 2025, npm classic tokens have been permanently revoked. You must use Granular Access Tokens for CI/CD automation.

Creating a Granular Access Token

Go to npmjs.com → Sign in
Click your avatar → Access Tokens
Click Generate New Token
Configure the token:
- Token name:
```
gitlab-ci-publish
```
  (or similar descriptive name)
- Expiration: Up to 90 days (maximum allowed for write tokens)
- Permissions: Read and write
- Packages: All packages or select
```
claude-toggle
```
  specifically
- 2FA: Enable "Bypass 2FA for automation" for CI/CD workflows
Click Generate token and copy it immediately (it won't be shown again)

Alternatively, create a token via CLI:

npm token create

GitLab CI/CD Configuration

Go to your GitLab project → Settings → CI/CD → Variables
Add a new variable:
- Key:
```
NPM_TOKEN
```
- Value: Your granular access token
- Type: Variable
- Protected: Yes (recommended)
- Masked: Yes
If using protected variables, ensure version tags are protected:
- Go to Settings → Repository → Protected tags
- Add pattern:
```
v*
```

Token Rotation

Since granular tokens expire after 90 days maximum, set a reminder to rotate the token before expiration. Update the

NPM_TOKEN

variable in GitLab with the new token.

Publishing a Release

# 1. Update version in package.json and claude-toggle
# 2. Commit changes
git add -A && git commit -m "chore: bump version to X.Y.Z"

# 3. Create and push version tag
git tag vX.Y.Z
git push origin main --tags

The pipeline will automatically validate and publish to npm.

Development

Project Structure

claude-toggle/
├── claude-toggle              # Main executable script
├── providers.json             # Provider configuration
├── package.json               # npm package manifest
├── bin/
│   ├── wrapper.js             # Node.js wrapper for npm
│   └── postinstall.js         # Post-install config setup
├── docs/
│   └── NPM_PUBLISHING.md      # Publishing guide
├── .claude/
│   └── commands/
│       └── add-provider.md    # Interactive provider wizard
├── CLAUDE.md                  # Claude Code project instructions
├── PROVIDERS.md               # Provider configuration guide
├── DEVELOPER_GUIDE.md         # Development documentation
├── LICENSE                    # MIT license
└── README.md                  # This file

Running Tests

# Test help output
./claude-toggle --help

# Test provider listing
./claude-toggle --list-providers

# Validate all providers
./claude-toggle --validate --provider anthropic
./claude-toggle --validate --provider glm  # Requires ZAI_API_KEY

Contributing

See DEVELOPER_GUIDE.md for development setup, coding standards, and contribution guidelines.

Fork the repository
Create a feature branch:
```
git checkout -b feature/my-feature
```
Make changes and test thoroughly
Commit with clear messages
Open a Pull Request

How It Works

Configuration Loading - Finds and parses
```
providers.json
```
Provider Validation - Checks required environment variables
Environment Export - Sets provider-specific env vars for subprocess
Process Replacement - Uses
```
exec claude
```
to launch Claude Code

All environment changes are scoped to the Claude Code subprocess - your shell environment remains unchanged.

Platform Compatibility

Platform	npm	Manual
macOS	Full support	Full support
Linux	Full support	Full support
Windows	Via WSL/Git Bash	Via WSL/Git Bash

Windows Users

claude-toggle is a bash script and requires a Unix-like environment:

Windows Subsystem for Linux (WSL) - Recommended

# Install WSL, then inside WSL:
npm install -g @sekora_ai/claude-toggle

Git Bash - With Python 3 installed

npm install -g @sekora_ai/claude-toggle

Troubleshooting

"Configuration file not found"

Create a configuration file in one of the search paths:

mkdir -p ~/.config/claude-providers
cp providers.json ~/.config/claude-providers/

"Missing required credentials"

The error message includes detailed setup instructions. For example, for GLM:

export ZAI_API_KEY="your-api-key-here"

"python3: command not found"

Install Python 3:

# macOS (using Homebrew)
brew install python3

# Ubuntu/Debian
sudo apt install python3

# Fedora
sudo dnf install python3

# Windows (WSL)
sudo apt install python3

License

MIT License - See LICENSE for details.

claude-toggle

Features

Provider-agnostic architecture - JSON-based configuration for easy provider management
Zero file modifications - All changes are scoped to the subprocess environment
Pass-through design - All Claude Code CLI options work transparently
Actionable error messages - Missing credentials trigger detailed setup instructions
Extensible - Add new providers by editing a single JSON file

Prerequisites

Bash (version 4.0+)
Python 3 (for JSON parsing, no external packages required)
Claude Code CLI installed and available as
```
claude
```

Installation

Option 1: npm (Recommended)

npm install -g @sekora_ai/claude-toggle

This works on macOS, Linux, and Windows (via WSL or Git Bash).

Option 2: Manual Installation

# Clone the repository
git clone https://gitlab.com/sekora-ai/claude-code/claude-toggle.git
cd claude-toggle
chmod +x claude-toggle

# Copy default config to user directory
mkdir -p ~/.config/claude-providers
cp providers.json ~/.config/claude-providers/

# Add to PATH (choose your shell)
# For bash:
echo 'export PATH="$HOME/path/to/claude-toggle:$PATH"' >> ~/.bashrc
source ~/.bashrc

# For zsh:
echo 'export PATH="$HOME/path/to/claude-toggle:$PATH"' >> ~/.zshrc
source ~/.zshrc

Usage

Basic Usage

# Launch with default provider (Anthropic)
./claude-toggle

# Launch with specific provider
./claude-toggle --provider glm

# List available providers
./claude-toggle --list-providers

# Validate provider configuration
./claude-toggle --validate --provider glm

Pass-through Options

All unrecognized options are forwarded to the Claude Code CLI:

# Pass options to Claude Code
./claude-toggle --provider glm --dangerously-skip-permissions

# Any Claude Code option works
./claude-toggle --provider anthropic --help

Command Reference

Option	Description
`-p, --provider <name>`	Select a specific provider
`-l, --list-providers`	List all available providers
`--validate`	Validate provider configuration without launching
`-v, --verbose`	Enable verbose output
`-h, --help`	Show help message
`--glm`	Legacy alias for `--provider glm`

Configuration

Configuration File Location

The script searches for

providers.json

in this order:

~/.config/claude-providers/providers.json

(recommended)

```
~/.claude-providers.json
```
```
<script-directory>/providers.json
```

Provider Configuration

Providers are configured in

providers.json

{
  "version": "1.0",
  "default_provider": "anthropic",
  "providers": {
    "anthropic": {
      "description": "Anthropic's official API",
      "enabled": true,
      "env_vars": {},
      "validation": {}
    },
    "glm": {
      "description": "Z.AI GLM models via proxy",
      "enabled": true,
      "env_vars": {
        "ANTHROPIC_AUTH_TOKEN": {
          "value": "${ZAI_API_KEY}",
          "required": true
        },
        "ANTHROPIC_BASE_URL": {
          "value": "https://api.z.ai/api/anthropic"
        }
      },
      "validation": {
        "required_env_vars": ["ZAI_API_KEY"]
      }
    }
  }
}

Adding New Providers

Interactive wizard (recommended):

If you're using Claude Code in this repository, run:

/add-provider

This walks you through the entire process interactively.

Manual configuration:

See PROVIDERS.md for detailed instructions on adding new providers.

Quick example:

"my-provider": {
  "description": "My custom provider",
  "enabled": true,
  "env_vars": {
    "ANTHROPIC_AUTH_TOKEN": {"value": "${MY_API_KEY}"},
    "ANTHROPIC_BASE_URL": {"value": "https://api.example.com/v1"}
  },
  "validation": {
    "required_env_vars": ["MY_API_KEY"]
  }
}

Built-in Providers

Provider	Description	Required Env Var
`anthropic`	Anthropic's official API (default)	None (uses default auth)
`glm`	Z.AI GLM models via proxy	`ZAI_API_KEY`

Examples

Using Z.AI GLM Provider

# Set your API key
export ZAI_API_KEY="your-key-here"

# Launch Claude Code with GLM
./claude-toggle --provider glm

Validating Before Launch

# Check if provider is properly configured
./claude-toggle --validate --provider glm

# Output: Provider 'glm' is valid and ready to use

Verbose Mode

# See which provider is being used
./claude-toggle --verbose --provider glm

# Output: Using provider: glm

CI/CD Setup (For Maintainers)

This project uses GitLab CI/CD to automatically publish to npm when version tags are pushed.

npm Token Setup

Important: As of December 9, 2025, npm classic tokens have been permanently revoked. You must use Granular Access Tokens for CI/CD automation.

Creating a Granular Access Token

Go to npmjs.com → Sign in
Click your avatar → Access Tokens
Click Generate New Token
Configure the token:
- Token name:
```
gitlab-ci-publish
```
  (or similar descriptive name)
- Expiration: Up to 90 days (maximum allowed for write tokens)
- Permissions: Read and write
- Packages: All packages or select
```
claude-toggle
```
  specifically
- 2FA: Enable "Bypass 2FA for automation" for CI/CD workflows
Click Generate token and copy it immediately (it won't be shown again)

Alternatively, create a token via CLI:

npm token create

GitLab CI/CD Configuration

Go to your GitLab project → Settings → CI/CD → Variables
Add a new variable:
- Key:
```
NPM_TOKEN
```
- Value: Your granular access token
- Type: Variable
- Protected: Yes (recommended)
- Masked: Yes
If using protected variables, ensure version tags are protected:
- Go to Settings → Repository → Protected tags
- Add pattern:
```
v*
```

Token Rotation

Since granular tokens expire after 90 days maximum, set a reminder to rotate the token before expiration. Update the

NPM_TOKEN

variable in GitLab with the new token.

Publishing a Release

# 1. Update version in package.json and claude-toggle
# 2. Commit changes
git add -A && git commit -m "chore: bump version to X.Y.Z"

# 3. Create and push version tag
git tag vX.Y.Z
git push origin main --tags

The pipeline will automatically validate and publish to npm.

Development

Project Structure

claude-toggle/
├── claude-toggle              # Main executable script
├── providers.json             # Provider configuration
├── package.json               # npm package manifest
├── bin/
│   ├── wrapper.js             # Node.js wrapper for npm
│   └── postinstall.js         # Post-install config setup
├── docs/
│   └── NPM_PUBLISHING.md      # Publishing guide
├── .claude/
│   └── commands/
│       └── add-provider.md    # Interactive provider wizard
├── CLAUDE.md                  # Claude Code project instructions
├── PROVIDERS.md               # Provider configuration guide
├── DEVELOPER_GUIDE.md         # Development documentation
├── LICENSE                    # MIT license
└── README.md                  # This file

Running Tests

# Test help output
./claude-toggle --help

# Test provider listing
./claude-toggle --list-providers

# Validate all providers
./claude-toggle --validate --provider anthropic
./claude-toggle --validate --provider glm  # Requires ZAI_API_KEY

Contributing

See DEVELOPER_GUIDE.md for development setup, coding standards, and contribution guidelines.

Fork the repository
Create a feature branch:
```
git checkout -b feature/my-feature
```
Make changes and test thoroughly
Commit with clear messages
Open a Pull Request

How It Works

Configuration Loading - Finds and parses
```
providers.json
```
Provider Validation - Checks required environment variables
Environment Export - Sets provider-specific env vars for subprocess
Process Replacement - Uses
```
exec claude
```
to launch Claude Code

All environment changes are scoped to the Claude Code subprocess - your shell environment remains unchanged.

Platform Compatibility

Platform	npm	Manual
macOS	Full support	Full support
Linux	Full support	Full support
Windows	Via WSL/Git Bash	Via WSL/Git Bash

Windows Users

claude-toggle is a bash script and requires a Unix-like environment:

Windows Subsystem for Linux (WSL) - Recommended

# Install WSL, then inside WSL:
npm install -g @sekora_ai/claude-toggle

Git Bash - With Python 3 installed

npm install -g @sekora_ai/claude-toggle

Troubleshooting

"Configuration file not found"

Create a configuration file in one of the search paths:

mkdir -p ~/.config/claude-providers
cp providers.json ~/.config/claude-providers/

"Missing required credentials"

The error message includes detailed setup instructions. For example, for GLM:

export ZAI_API_KEY="your-api-key-here"

"python3: command not found"

Install Python 3:

# macOS (using Homebrew)
brew install python3

# Ubuntu/Debian
sudo apt install python3

# Fedora
sudo dnf install python3

# Windows (WSL)
sudo apt install python3

License

MIT License - See LICENSE for details.

claude-toggle

Related Skills

<h1 align="center">

- Identify gaps

2. Apply Deepthink Protocol (reason about dependencies