ccproxy-tools Setup

ccproxy-tools Setup

Configure Claude Code to use ccproxy/LiteLLM with Claude Pro/Max subscription, GitHub Copilot, or other LLM providers.

Step 1: Check Prerequisites

Check if uv is installed:

which uv

If not installed, install it:

curl -LsSf https://astral.sh/uv/install.sh | sh

Then reload shell or run source ~/.bashrc (or ~/.zshrc).

Step 2: Ask Provider Choice

Use AskUserQuestion:

• question: "Which LLM provider do you want to use with Claude Code?"
• header: "Provider"
• options:
  • label: "Claude Pro/Max (ccproxy)" description: "Use your Claude subscription via OAuth - no API keys needed"
  • label: "GitHub Copilot (LiteLLM)" description: "Use GitHub Copilot subscription via LiteLLM proxy"
  • label: "OpenAI API (LiteLLM)" description: "Use OpenAI models via LiteLLM proxy"
  • label: "Gemini API (LiteLLM)" description: "Use Google Gemini models via LiteLLM proxy"

Step 3: Install Proxy Tool

If Claude Pro/Max (ccproxy)

Install and initialize ccproxy:

uv tool install ccproxy
ccproxy init

If GitHub Copilot, OpenAI, or Gemini (LiteLLM)

Install LiteLLM:

uv tool install 'litellm[proxy]'

Step 4: Configure LiteLLM (if applicable)

For GitHub Copilot

Auto-detect VS Code and Copilot versions:

# Get VS Code version
VSCODE_VERSION=$(code --version 2> /dev/null | head -1 || echo "1.96.0")

# Find Copilot Chat extension version
COPILOT_VERSION=$(ls ~/.vscode/extensions/ 2> /dev/null | grep "github.copilot-chat-" | sed 's/github.copilot-chat-//' | sort -V | tail -1 || echo "0.26.7")

Create ~/.litellm/config.yaml with detected versions:

general_settings:
  master_key: sk-dummy
litellm_settings:
  drop_params: true
model_list:
  - model_name: "*"
    litellm_params:
      model: "github_copilot/*"
      extra_headers:
        editor-version: "vscode/${VSCODE_VERSION}"
        editor-plugin-version: "copilot-chat/${COPILOT_VERSION}"
        Copilot-Integration-Id: "vscode-chat"
        user-agent: "GitHubCopilotChat/${COPILOT_VERSION}"

For OpenAI API

Ask for OpenAI API key using AskUserQuestion:

• question: "Enter your OpenAI API key (starts with sk-):"
• header: "OpenAI Key"
• options:
  • label: "I have it ready" description: "I'll paste my OpenAI API key"
  • label: "Skip for now" description: "I'll configure it later"

Create ~/.litellm/config.yaml:

general_settings:
  master_key: sk-dummy
litellm_settings:
  drop_params: true
model_list:
  - model_name: "*"
    litellm_params:
      model: openai/gpt-4o
      api_key: ${OPENAI_API_KEY}

For Gemini API

Ask for Gemini API key using AskUserQuestion:

• question: "Enter your Gemini API key:"
• header: "Gemini Key"
• options:
  • label: "I have it ready" description: "I'll paste my Gemini API key"
  • label: "Skip for now" description: "I'll configure it later"

Create ~/.litellm/config.yaml:

general_settings:
  master_key: sk-dummy
litellm_settings:
  drop_params: true
model_list:
  - model_name: "*"
    litellm_params:
      model: gemini/gemini-2.5-flash
      api_key: ${GEMINI_API_KEY}

Step 5: Setup Auto-Start Service

Detect platform and create appropriate service:

macOS (launchd)

For ccproxy, create ~/Library/LaunchAgents/com.ccproxy.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.ccproxy</string>
    <key>ProgramArguments</key>
    <array>
        <string>${HOME}/.local/bin/ccproxy</string>
        <string>start</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>${HOME}/.local/share/ccproxy/stdout.log</string>
    <key>StandardErrorPath</key>
    <string>${HOME}/.local/share/ccproxy/stderr.log</string>
</dict>
</plist>

For LiteLLM, create ~/Library/LaunchAgents/com.litellm.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.litellm</string>
    <key>ProgramArguments</key>
    <array>
        <string>${HOME}/.local/bin/litellm</string>
        <string>--config</string>
        <string>${HOME}/.litellm/config.yaml</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>${HOME}/.local/share/litellm/stdout.log</string>
    <key>StandardErrorPath</key>
    <string>${HOME}/.local/share/litellm/stderr.log</string>
</dict>
</plist>

Load and start the service:

launchctl load ~/Library/LaunchAgents/com.ccproxy.plist # or com.litellm.plist

Linux (systemd user service)

For ccproxy, create ~/.config/systemd/user/ccproxy.service:

[Unit]
Description=ccproxy LLM Proxy

[Service]
ExecStart=%h/.local/bin/ccproxy start
Restart=always
RestartSec=5

[Install]
WantedBy=default.target

For LiteLLM, create ~/.config/systemd/user/litellm.service:

[Unit]
Description=LiteLLM Proxy

[Service]
ExecStart=%h/.local/bin/litellm --config %h/.litellm/config.yaml
Restart=always
RestartSec=5

[Install]
WantedBy=default.target

Enable and start the service:

systemctl --user daemon-reload
systemctl --user enable --now ccproxy # or litellm

Step 6: Authenticate (ccproxy only)

For ccproxy, tell the user:

The proxy is starting. A browser window will open for authentication.

1. Sign in with your Claude Pro/Max account
2. Authorize the connection
3. Return here after successful authentication

Wait for authentication to complete.

Step 7: Verify Proxy is Running

Check if proxy is healthy:

curl -s http://localhost:4000/health

Retry up to 5 times with 3-second delays if not responding.

If proxy is not healthy after retries:

• Show error and troubleshooting steps
• Do NOT proceed to update settings
• Exit

Step 8: Confirm Before Updating Settings

Use AskUserQuestion:

• question: "Proxy is running. Ready to configure Claude Code to use it?"
• header: "Configure"
• options:
  • label: "Yes, configure now" description: "Update settings to use the proxy (requires restart)"
  • label: "No, not yet" description: "Keep current settings, I'll configure later"

If user selects "No, not yet":

• Tell them they can run /ccproxy-tools:setup again when ready
• Exit without changing settings

Step 9: Update Settings

1. Read current ~/.claude/settings.json
2. Create backup at ~/.claude/settings.json.backup
3. Add to env section based on provider:

For ccproxy:

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:4000"
  }
}

For LiteLLM:

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:4000",
    "ANTHROPIC_AUTH_TOKEN": "sk-dummy"
  }
}

4. Write updated settings

Step 10: Confirm Success

Tell the user:

Configuration complete!

IMPORTANT: Restart Claude Code for changes to take effect.
- Exit Claude Code
- Run `claude` again

The proxy will start automatically on system boot.

To verify after restart:
- Claude Code should connect to the proxy at localhost:4000
- Check proxy logs: ~/Library/LaunchAgents/*.log (macOS) or journalctl --user -u ccproxy (Linux)

Recovery Instructions

Always show these recovery instructions:

If Claude Code stops working after setup:

1. Check proxy status:
   curl http://localhost:4000/health

2. Restart proxy:
   macOS: launchctl kickstart -k gui/$(id -u)/com.ccproxy
   Linux: systemctl --user restart ccproxy

3. Check proxy logs:
   macOS: cat ~/.local/share/ccproxy/stderr.log
   Linux: journalctl --user -u ccproxy

4. Restore original settings (removes proxy):
   cp ~/.claude/settings.json.backup ~/.claude/settings.json

   Or manually edit ~/.claude/settings.json and remove:
   - ANTHROPIC_BASE_URL
   - ANTHROPIC_AUTH_TOKEN (if present)

Troubleshooting

If proxy setup fails:

Common fixes:
1. Port in use - Check if another process uses port 4000: lsof -i :4000
2. Service not starting - Check logs in ~/.local/share/ccproxy/ or ~/.local/share/litellm/
3. Authentication failed - Re-run setup to re-authenticate
4. Permission denied - Ensure ~/.local/bin is in PATH
5. Config invalid - Verify ~/.litellm/config.yaml syntax