5.0 KiB
ppswitch - ProxyPilot Config Switcher
ppswitch is a lightweight CLI tool that switches AI coding agents between proxy mode (through ProxyPilot) and native mode (direct API access). Think of it like nvm for Node versions, but for AI agent configurations.
Installation
Via bun (recommended)
bun install -g ppswitch
Via npm
npm install -g ppswitch
Via Go
go install github.com/Finesssee/ProxyPilot/cmd/ppswitch@latest
Manual Download
Download pre-built binaries from GitHub Releases.
Available binaries:
ppswitch-darwin-amd64- macOS Intelppswitch-darwin-arm64- macOS Apple Siliconppswitch-linux-amd64- Linux x64ppswitch-linux-arm64- Linux ARM64ppswitch-windows-amd64.exe- Windows x64
Usage
ppswitch # Show status of all agents
ppswitch <agent> # Show status of specific agent
ppswitch <agent> <mode> # Switch agent to mode
ppswitch -h, --help # Show help
ppswitch -v, --version # Show version
Supported Agents
| Agent | CLI Tool | Config Location |
|---|---|---|
claude |
Claude Code | ~/.claude/settings.json |
gemini |
Gemini CLI | ~/.gemini/settings.json |
codex |
Codex CLI | ~/.codex/config.toml |
opencode |
OpenCode | ~/.opencode/config.json |
droid |
Factory Droid | ~/.factory/settings.json |
cursor |
Cursor IDE | ~/.cursor/config.json |
kilo |
Kilo Code* | VS Code settings |
roocode |
RooCode* | VS Code settings |
*VS Code extensions require manual configuration - ppswitch will display instructions.
Modes
| Mode | Description |
|---|---|
proxy |
Route through ProxyPilot (http://127.0.0.1:8317) |
native |
Use direct API access (restore original config) |
Examples
Check all agent statuses
$ ppswitch
Agent Status:
claude proxy ~/.claude/settings.json
gemini native ~/.gemini/settings.json
codex native ~/.codex/config.toml
droid not found
Switch Claude to proxy mode
$ ppswitch claude proxy
Switched Claude Code to proxy mode
Config: ~/.claude/settings.json
Backup: ~/.claude/settings.json.native.json
Switch Gemini back to native mode
$ ppswitch gemini native
Switched Gemini CLI to native mode
Restored from: ~/.gemini/settings.json.native.json
Check single agent status
$ ppswitch claude
Claude Code: proxy
Config: ~/.claude/settings.json
How It Works
Switching to proxy mode
- Backs up current config to
<config>.native.json - Updates config to point to
http://127.0.0.1:8317 - Preserves all other settings (API keys, preferences, etc.)
Switching to native mode
- Restores config from
<config>.native.jsonbackup - Removes backup file after successful restore
- Original API keys and settings are restored
Config Detection
ppswitch automatically detects which mode an agent is in by checking:
- If config contains
127.0.0.1:8317→ proxy mode - If backup file exists → was previously in proxy mode
- Otherwise → native mode
Agent-Specific Notes
Claude Code
Config location: ~/.claude/settings.json
Proxy mode sets:
{
"env": {
"ANTHROPIC_BASE_URL": "http://127.0.0.1:8317"
}
}
Codex CLI
Config location: ~/.codex/config.toml
Proxy mode sets:
[openai]
api_base_url = "http://127.0.0.1:8317"
Gemini CLI
Config location: ~/.gemini/settings.json
Proxy mode sets the API endpoint to ProxyPilot.
Kilo Code & RooCode
These are VS Code extensions that require manual configuration:
- Open VS Code Settings (Ctrl+,)
- Search for the extension settings
- Update the API base URL to
http://127.0.0.1:8317
ppswitch will display these instructions when you run:
ppswitch kilo proxy
ppswitch roocode proxy
Troubleshooting
"Config not found"
The agent's config file doesn't exist. Run the agent once to create it, or create the config manually.
"Failed to backup config"
Check file permissions on the config directory.
"Already in proxy/native mode"
The agent is already configured for the requested mode. No changes made.
CI/CD
ppswitch is published automatically:
-
Release workflow (
.github/workflows/ppswitch-release.yml)- Triggered by
ppswitch-v*tags - Builds binaries for all platforms
- Creates GitHub release with assets
- Triggered by
-
Publish workflow (
.github/workflows/ppswitch-bun.yml)- Triggered after successful release build
- Publishes to npm registry via bun
Creating a new release
# Update version in cmd/ppswitch/main.go and bun/ppswitch/package.json
git tag ppswitch-v0.2.0
git push origin ppswitch-v0.2.0