# 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](https://claude.ai/code) installed and available as `claude`

## Installation

### Option 1: npm (Recommended)

```bash
npm install -g @sekora_ai/claude-toggle
```

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

### Option 2: Manual Installation

```bash
# 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

```bash
# 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:

```bash
# 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:

1. `~/.config/claude-providers/providers.json` (recommended)
2. `~/.claude-providers.json`
3. `<script-directory>/providers.json`

### Provider Configuration

Providers are configured in `providers.json`:

```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](PROVIDERS.md) for detailed instructions on adding new providers.

**Quick example:**

```json
"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

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

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

### Validating Before Launch

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

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

### Verbose Mode

```bash
# 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

1. Go to [npmjs.com](https://www.npmjs.com) → Sign in
2. Click your avatar → **Access Tokens**
3. Click **Generate New Token**
4. 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
5. Click **Generate token** and copy it immediately (it won't be shown again)

Alternatively, create a token via CLI:
```bash
npm token create
```

#### GitLab CI/CD Configuration

1. Go to your GitLab project → **Settings** → **CI/CD** → **Variables**
2. Add a new variable:
   - **Key**: `NPM_TOKEN`
   - **Value**: Your granular access token
   - **Type**: Variable
   - **Protected**: Yes (recommended)
   - **Masked**: Yes
3. 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

```bash
# 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

```bash
# 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](DEVELOPER_GUIDE.md) for development setup, coding standards, and contribution guidelines.

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

## How It Works

1. **Configuration Loading** - Finds and parses `providers.json`
2. **Provider Validation** - Checks required environment variables
3. **Environment Export** - Sets provider-specific env vars for subprocess
4. **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:

1. **Windows Subsystem for Linux (WSL)** - Recommended
   ```bash
   # Install WSL, then inside WSL:
   npm install -g @sekora_ai/claude-toggle
   ```

2. **Git Bash** - With Python 3 installed
   ```bash
   npm install -g @sekora_ai/claude-toggle
   ```

## Troubleshooting

### "Configuration file not found"

Create a configuration file in one of the search paths:

```bash
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:

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

### "python3: command not found"

Install Python 3:

```bash
# 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](LICENSE) for details.