Claude Overlay

claude-overlay

Manage project-level Claude Code configuration for custom model providers.

When using Claude Code through a proxy or third-party endpoint — Databricks, Amazon Bedrock, OpenRouter, LiteLLM, or others — Anthropic's native WebSearch and WebFetch tools may not work because they rely on Anthropic's own infrastructure. claude-overlay solves this by creating a project-level configuration overlay that:

- Routes Claude Code to your custom endpoint
- Replaces native web search with MCP-based alternatives (Tavily + DuckDuckGo)
- Preserves all your existing project settings and MCP servers
- Toggles cleanly between custom provider and native Anthropic modes

Install

Homebrew (macOS / Linux)

curl

From source

Requirements: bash, python3 >= 3.7, npx (Node.js)

Quick Start

Commands

Enable / Disable

A key feature of claude-overlay is the ability to switch between your custom provider and native Anthropic without losing any project configuration.

Disabling the overlay

This surgically removes only the keys that claude-overlay manages:
- Provider env vars (ANTHROPIC_MODEL, ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, etc.)
- MCP web search servers (tavily, duckduckgo)
- Permission rules for MCP tools and native tool deny rules

Everything else — your custom permissions, other MCP servers, other env vars — is left untouched.

After disabling, Claude Code falls back to your global settings (~/.claude/settings.json), which typically means direct Anthropic API with native WebSearch/WebFetch.

Enabling the overlay

This merges the overlay keys back into your project config without duplicating anything. Your custom settings remain intact.

Checking status

Shows a complete view of your project's state:

What gets preserved

Typical workflow

Multi-Provider & Team…