claude-wrapper

The installer writes a process wrapper to ~/.local/bin/claude that shadows the real Claude Code binary. When you run claude, the wrapper:

1. Finds the real binary (portable PATH iteration, skipping itself)
2. Fetches the latest team config from this repo, validates it against an integrity check, caches it for 5 minutes, falls back to stale cache on network failure
3. Sources the config to set ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, model defaults, per-project API keys, and ANTHROPIC_CUSTOM_HEADERS (auto-injects x-github-repo: <project> for LiteLLM per-repo attribution)
4. Optionally sources ~/.config/claude/middleware.sh for custom pre-launch hooks (errors are trapped with actionable messages)
5. execs the real Claude Code with all original arguments

Config override chain: Remote defaults (claude-env.sh) → local overrides (~/.config/claude/local.env) → environment variables. Local values persist across remote config updates — the TTL-based refresh only re-fetches the remote config, never touching your local settings.

The wrapper detects the current project from the git remote (or directory name) and looks up a project-specific API key field in your 1Password item. If no project-specific field exists, it falls back to the default API Key field.

1Password item: "op://Vault/your-litellm-item"
 ├── API Key (default fallback)
 ├── backend-api (project-specific)
 └── customer-portal (project-specific)

Override project detection: CLAUDE_PROJECT=my-project claude

Every request to the LiteLLM gateway is automatically tagged with an x-github-repo: <project> header so the gateway can attribute usage, spend, and rate-limits per repository — zero developer setup.

The value comes from the same project-detection logic used for API key lookup (CLAUDE_PROJECT), so a request from ~/code/your-org/backend-api is tagged x-github-repo: backend-api.

If you've already set ANTHROPIC_CUSTOM_HEADERS (via local.env, shell environment, or middleware.sh), the auto-injected header is appended on a new line so your custom headers are preserved:

x-team: platform
x-github-repo: backend-api

To suppress the header on a specific project (rare — e.g., experimental scratch work you don't want attributed), strip it in your personal ~/.config/claude/middleware.sh. The team config does not provide a built-in opt-out.

Files:

The installer stores your LiteLLM URL and 1Password item in ~/.config/claude/local.env. These values override the remote defaults and are never touched by automatic updates.

# View current settings
cat ~/.config/claude/local.env
# Re-run installer to change values (shows current as defaults)
curl -fsSL https://raw.githubusercontent.com/aproorg/claude-wrapper/main/install.sh | bash

The file uses simple KEY="VALUE" format and has 0600 permissions.

Claude Code can send MCP tool names up front and fetch individual schemas on demand via a ToolSearch tool, instead of inlining every schema in every request. It enables this automatically only when ANTHROPIC_BASE_URL is a first-party Anthropic host — sessions through the LiteLLM gateway fail that check, so it must be opted into explicitly.

The saving is large. Measured on this wrapper with four MCP servers connected, tool schemas were 86% of a trivial request's payload (~44K tokens); per-turn prompt tokens across a real session went from ~68,900 to ~20,700.

Opt in with both lines in local.env (~/.config/claude/local.env, or %APPDATA%\claude\local.env):

CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=0
ENABLE_TOOL_SEARCH=true

Both are required: tool search rides on the advanced-tool-use-2025年11月20日 beta, which the default suppression strips, so ENABLE_TOOL_SEARCH alone does nothing. Lifting the suppression also re-enables the other experimental betas — there is no per-beta switch. Besides true, the flag accepts auto and auto:N.

Verified against litellm.ai.apro.is on Bedrock: prompt-cache reads stayed monotonic with zero misses, tool_reference blocks round-tripped, and MCP tools resolved on demand. Works on opus-4-7/opus-4-8/opus-5 and sonnet-4-6/sonnet-5. haiku-4-5 rejects tools[].custom.defer_loading with HTTP 400 — so don't combine this with CLAUDE_CODE_SUBAGENT_MODEL pinned to haiku, or every subagent turn fails.

Create ~/.config/claude/middleware.sh to run custom shell commands before Claude launches. The file is sourced (not executed), so it can export environment variables, modify PATH, or run setup commands.

# Example: add a custom env var
echo 'export MY_CUSTOM_VAR="hello"' > ~/.config/claude/middleware.sh
# Example: prepend to PATH
echo 'export PATH="/opt/my-tools/bin:$PATH"' > ~/.config/claude/middleware.sh

• The file is optional — if missing, nothing happens.
• Errors in middleware are caught and reported with an actionable message (file path + fix instructions).

irm https://raw.githubusercontent.com/aproorg/claude-wrapper/main/install.ps1 | iex

The installer:

1. Downloads claudestart.ps1 to %LOCALAPPDATA%\Programs\claude-wrapper\
2. Creates a claudestart.cmd shim so it works from cmd.exe too
3. Adds the install directory to your user PATH
4. Prompts for your LiteLLM base URL and 1Password item reference

Note: On Windows the command is claudestart (not claude) because Windows doesn't support the same binary-shadowing trick used on macOS/Linux.

Get-Command claudestart # Should show the .cmd shim
$env:CLAUDE_DEBUG = "1"; claudestart # Shows resolved config

When testing a PR or unmerged branch, you must set $env:CLAUDE_ENV_URL to the branch's claude-env.sh URL before running the installer. Without it, the installer falls back to main and downloads sibling files (including claudestart.ps1) from there — which is almost certainly not what you want when testing a branch.

$base = "https://raw.githubusercontent.com/aproorg/claude-wrapper/<branch-name>"
$env:CLAUDE_ENV_URL = "$base/claude-env.sh"
$env:CLAUDE_FORCE = "1" # overwrite existing wrapper without backup
irm "$base/install.ps1" | iex

Verify the install came from the branch by checking the [INFO] Source: line — it should reference your branch, not main. The installer also patches the installed claudestart.ps1 so subsequent launches keep fetching from that branch.

• Claude Code installed (npm global install or standalone)
• 1Password CLI (op.exe) with CLI integration enabled
• PowerShell 5.1+ (ships with Windows 10/11) or PowerShell 7+
• git (for project detection)

# Clear all caches (API keys + remote config)
claudestart --clear-cache
# Force refresh config cache only
Remove-Item "$env:LOCALAPPDATA\claude\env-remote.sh"
# Re-run installer to update local settings
irm https://raw.githubusercontent.com/aproorg/claude-wrapper/main/install.ps1 | iex
# Force reinstall wrapper (e.g. to pick up updates to claudestart.ps1)
$env:CLAUDE_FORCE = "1"; irm https://raw.githubusercontent.com/aproorg/claude-wrapper/main/install.ps1 | iex
# Debug mode
$env:CLAUDE_DEBUG = "1"; claudestart

If you prefer not to use the installer:

1. Run Set-ExecutionPolicy RemoteSigned in an elevated PowerShell (once)
2. Clone the repo and copy claudestart.ps1 to a directory on your PATH
3. Create a claudestart.cmd next to it with:

   @powershell -ExecutionPolicy Bypass -File "%~dp0claudestart.ps1" %*
   

Follow the macOS/Linux instructions inside your WSL shell — WSL uses the bash wrapper, not the PowerShell one.

Add to your settings.json:

{
 "claudeCode.environmentVariables": [
 { "name": "CLAUDE_CODE_SKIP_AUTH_LOGIN", "value": "1" }
 ],
 "claudeCode.claudeProcessWrapper": "claudestart.cmd"
}

Add to your settings.json:

{
 "claudeCode.environmentVariables": [
 { "name": "CLAUDE_CODE_SKIP_AUTH_LOGIN", "value": "1" }
 ],
 "claudeCode.claudeProcessWrapper": "/Users/YOU/.local/bin/claude"
}