claude-overlay

claude-overlay · mzmmoazam/claude-overlay · ★ 2 · last commit 2026-05-14

Primitive shape

No installable primitives

Summary

claude-overlay — Summary

claude-overlay is a bash + Python CLI that manages project-level Claude Code configuration for custom model providers (Databricks, Amazon Bedrock, OpenRouter, LiteLLM, Cloudflare) by creating an "overlay" in .claude/settings.local.json and .mcp.json that routes Claude Code to a custom endpoint and replaces native WebSearch/WebFetch tools with MCP-based alternatives (Tavily + DuckDuckGo). The key design insight is surgical configuration management: only the provider-specific keys are toggled (ANTHROPIC_MODEL, ANTHROPIC_BASE_URL, env vars, MCP server entries, permission rules) while all user-custom settings are left untouched — enabling clean disable and enable without losing other project configuration. The tool supports multi-provider configs (configure multiple providers, switch with claude-overlay switch) and team sharing (export sanitized configs with export, import with teammates using import). It ships as a single bash script that delegates all JSON manipulation to a Python engine (lib/engine.py). Compared to seeds, claude-overlay occupies a narrow "provider credential management" niche with no workflow methodology, no skills, no hooks — it is a DevOps configuration utility for teams using Claude Code through enterprise proxies or alternative AI providers.

Overview

claude-overlay — Overview

Origin

Created by Mohammad Moazam (mzmmoazam on GitHub). Version 0.3.0. Available via Homebrew.

Problem Solved

When using Claude Code through a proxy or third-party endpoint (Databricks, Amazon Bedrock, OpenRouter, LiteLLM, Cloudflare), Anthropic's native WebSearch and WebFetch tools fail because they rely on Anthropic's own infrastructure. claude-overlay solves this by injecting provider-specific configuration into the project-level Claude Code config.

Design Principle

From the README:

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

Key Technical Pattern: Surgical Config Management

The overlay only writes/removes these specific keys:

env.ANTHROPIC_MODEL
env.ANTHROPIC_BASE_URL
env.ANTHROPIC_AUTH_TOKEN
MCP servers: tavily, duckduckgo
permissions.deny.WebSearch, permissions.deny.WebFetch
permissions.allow.mcp__tavily__*, permissions.allow.mcp__duckduckgo__*

Everything else (other env vars, other MCP servers, other permissions) is left untouched.

Use Cases

Developers using Claude Code via Databricks Model Serving
Teams accessing Claude via Amazon Bedrock
Organizations routing through OpenRouter or LiteLLM
Quickly toggling between corporate proxy endpoint and direct Anthropic API
Sharing provider configs within a team without leaking credentials

Implementation Approach

A bash script delegates JSON manipulation to a Python engine (lib/engine.py). The bash script handles UX (colors, prompts, path resolution); Python handles JSON read/write/merge operations deterministically.

Architecture

claude-overlay — Architecture

Distribution

Type: bash-script-bundle
Binary name: claude-overlay
Version: 0.3.0
Language: Bash + Python 3 (hybrid)
Runtime required: bash, python3 >= 3.7, npx (Node.js for MCP server bootstrap)

Install Methods

# Homebrew (macOS / Linux)
brew tap mzmmoazam/claude-overlay
brew install claude-overlay

# curl
curl -fsSL https://raw.githubusercontent.com/mzmmoazam/claude-overlay/main/install.sh | bash

# From source
git clone https://github.com/mzmmoazam/claude-overlay.git
cd claude-overlay && make install

Directory Tree

claude-overlay/
├── bin/
│   └── claude-overlay       # Main bash script (entry point)
├── lib/
│   ├── engine.py             # Python JSON manipulation engine
│   └── presets/              # Provider preset configs
├── test/                     # Shell tests
├── completions/              # Shell completion files
├── Makefile
├── install.sh
└── .shellcheckrc

Config Files

File	Purpose
`~/.config/claude-overlay/config.json`	User-level provider credentials (created by `configure`)
`.claude/settings.local.json`	Project-level overlay keys (MANAGED by claude-overlay)
`.mcp.json`	Project-level MCP server configs (MANAGED partially)
`.claude/provider-overlay.json`	Saved overlay state for enable/disable toggling

Target Files Written/Modified

Project:
├── .claude/
│   ├── settings.local.json    ← overlay adds/removes env vars + permissions
│   └── provider-overlay.json  ← stores overlay state
└── .mcp.json                  ← overlay adds/removes tavily/duckduckgo MCP servers

Architecture: Bash + Python Split

Bash (bin/claude-overlay): UX, path resolution, color output, command routing, preflight checks
Python (lib/engine.py): JSON read/write/merge, ensure_onboarding, overlay state management

The Python engine is called via python3 "$LIB_DIR/engine.py" <operation> and communicates via stdout.

Provider Support

Databricks (DATABRICKS_TOKEN env var)
Amazon Bedrock
OpenRouter
LiteLLM
Cloudflare
Any Anthropic-compatible endpoint

MCP Web Search Replacement

When overlay is active, native WebSearch/WebFetch are denied, replaced by:

Tavily MCP server (semantic search, via npx)
DuckDuckGo MCP server (via npx)

Components

claude-overlay — Components

CLI Commands (12 subcommands)

Command	Purpose
`claude-overlay configure`	Set up provider credentials (creates `~/.config/claude-overlay/config.json`)
`claude-overlay setup`	Create overlay in current project
`claude-overlay setup --dry-run`	Preview what setup would do without writing files
`claude-overlay disable`	Remove overlay keys, keep other project settings
`claude-overlay enable`	Restore overlay keys alongside other settings
`claude-overlay status`	Show current project state (detailed view)
`claude-overlay switch [provider]`	Switch active provider (multi-provider configs)
`claude-overlay export`	Export config for team sharing (stdout, secrets sanitized)
`claude-overlay import <file>`	Import a shared config file
`claude-overlay doctor`	Check setup health (config, env vars, project)
`claude-overlay self-update`	Update to latest release
`claude-overlay --version`	Print version

Python Engine Operations

The Python engine.py handles:

configure — write provider credentials to config.json
setup — merge overlay keys into settings.local.json + .mcp.json
disable — surgically remove overlay-managed keys only
enable — merge overlay keys back without duplicating
status — read and report current overlay state
export — produce sanitized config (secrets replaced with env:VAR_NAME references)
import — parse shared config and apply credentials
ensure_onboarding — stamp ~/.claude.json first-run flags (non-blocking)

Shell Completions

Supports bash, zsh, and fish completions via completions/ directory.

What Gets Preserved (Disable/Enable Invariant)

Key	Status after disable	Status after enable
`env.ANTHROPIC_MODEL`	Removed	Restored
`env.ANTHROPIC_BASE_URL`	Removed	Restored
`env.MY_CUSTOM_VAR`	Kept intact	Kept intact
`permissions.deny.WebSearch`	Removed	Restored
`mcp__tavily__*` allow	Removed	Restored
`Bash(your custom rule)`	Kept intact	Kept intact
`your-custom-mcp`	Kept intact	Kept intact
`tavily` MCP server	Removed	Restored
`duckduckgo` MCP server	Removed	Restored

No Hooks, No Skills, No MCP (Own)

claude-overlay configures other MCP servers (Tavily, DuckDuckGo) but ships no MCP server itself. No hooks, skills, or subagents.

Prompts

claude-overlay — Prompts

claude-overlay ships no prompt files, skills, or AI instructions — it is a pure configuration management CLI. The "prompts" it manages are Claude Code's native config keys that tell Claude which model endpoint to use and which tools are available.

Excerpt 1 — Generated settings.local.json (Overlay Active)

When claude-overlay setup runs, it merges these keys into .claude/settings.local.json:

{
  "env": {
    "ANTHROPIC_MODEL": "databricks-claude-opus-4-7",
    "ANTHROPIC_BASE_URL": "https://my-workspace.cloud.databricks.com/serving-endpoints/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "env:DATABRICKS_TOKEN"
  },
  "permissions": {
    "deny": ["WebSearch", "WebFetch"],
    "allow": [
      "mcp__tavily__tavily_search",
      "mcp__tavily__tavily_research",
      "mcp__duckduckgo__search"
    ]
  }
}

Technique: Environment-variable injection for AI routing. Rather than modifying Claude Code's global config, the overlay operates at the project level and uses Claude Code's env injection to route API calls. This makes the configuration contextual (per project, not per machine) and reversible.

Excerpt 2 — Generated .mcp.json (Overlay Active)

{
  "mcpServers": {
    "tavily": {
      "command": "npx",
      "args": ["-y", "@tavily/mcp-server"],
      "env": { "TAVILY_API_KEY": "${TAVILY_API_KEY}" }
    },
    "duckduckgo": {
      "command": "npx",
      "args": ["-y", "@mcp-server/duckduckgo"]
    },
    "your-existing-server": {
      "command": "...",
      "args": [...]
    }
  }
}

Technique: MCP server injection alongside existing servers. claude-overlay adds Tavily and DuckDuckGo to .mcp.json without touching the user's existing MCP servers — a non-destructive merge pattern.

Excerpt 3 — Status Output (Generated by `claude-overlay status`)

Claude Overlay — Project Status
/home/user/my-project

  Provider       ENABLED
  Model          databricks-claude-opus-4-7
  Endpoint       https://my-workspace.cloud.databricks.com/serving-endpoints/anthropic

  Managed MCP servers:
    ● tavily
    ● duckduckgo
  Other MCP servers (untouched):
    ● my-custom-server

  Native tools   denied: WebSearch, WebFetch
  MCP tools      pre-approved: mcp__tavily__*, mcp__duckduckgo__search
  Other allow    2 rule(s)

Technique: State transparency. The status command provides a clear separation between "overlay-managed" and "user-owned" keys, making the overlay's footprint auditable.

Uniqueness

claude-overlay — Uniqueness

differs_from_seeds

claude-overlay has no direct analog among the 11 seeds. It addresses a specific infrastructure problem — routing Claude Code through enterprise AI proxies — that none of the seeds consider. The most similar seed is agent-os (manages ~/.claude/ directory) and claude-conductor (markdown scaffold with settings conventions), but neither handles provider credential management or the native-tools-replacement problem. claude-overlay is the only tool in the batch (and likely the broader catalog) specifically designed for organizations using non-Anthropic endpoints with Claude Code, where native WebSearch/WebFetch become non-functional. Unlike all seeds, claude-overlay treats Claude Code's configuration as an infrastructure artifact requiring surgical GitOps-style management: only "owned" keys are modified, everything else is preserved, and changes are reversible.

Positioning

Primary differentiator: Surgical config management — the only tool that precisely tracks which config keys it "owns" and removes only those on disable, leaving all user-custom settings intact. This enables clean toggles between corporate proxy and direct Anthropic modes.
Secondary differentiator: Team sharing via sanitized export (secrets replaced with env: references). This allows credential-free config sharing — an operational pattern not seen in other config management tools in this batch.
Target user: Enterprise developers using Claude Code through Databricks, Bedrock, OpenRouter, or other Anthropic-compatible endpoints where native web tools fail.

Observable Failure Modes

Endpoint instability: If the custom provider endpoint goes down, Claude Code stops working and there's no automatic fallback — claude-overlay disable must be run manually.
MCP server cold start: Tavily and DuckDuckGo MCP servers are installed via npx -y, which may fail on networks with npm restrictions.
Python 3.7+ dependency: The engine requires Python 3.7+, which may not be available on minimal server environments.
Single-project scope: Each claude-overlay setup is per-project. Teams with many projects must run setup in each one, and there's no bulk configuration mechanism.
Stars indicate niche adoption (2): Despite solving a real enterprise problem, low community awareness suggests the tool is pre-discovery by its target audience.

Workflow

claude-overlay — Workflow

Initial Setup Workflow

# 1. Configure provider credentials (one-time)
claude-overlay configure
# → creates ~/.config/claude-overlay/config.json

# 2. Set env vars in shell profile
export DATABRICKS_TOKEN="your-token"
export TAVILY_API_KEY="your-key"

# 3. Set up overlay in project
cd your-project
claude-overlay setup

# 4. Verify
claude-overlay doctor

# 5. Launch Claude Code — now uses custom provider

Daily Toggle Workflow

# Working with Databricks
claude-overlay setup    # first time
claude-overlay status   # verify

# Switch to direct Anthropic temporarily
claude-overlay disable

# Back to Databricks
claude-overlay enable

Multi-Provider Workflow

# Set up multiple providers
claude-overlay configure    # configure Databricks
claude-overlay configure    # add OpenRouter (Databricks stays)

# Switch interactively
claude-overlay switch

# Or switch by name
claude-overlay switch openrouter

# Person A (team lead) exports
claude-overlay export > team-overlay.json
# → secrets replaced with env: references (e.g. "env:DATABRICKS_TOKEN")

# Person B (new team member) imports
claude-overlay import team-overlay.json
claude-overlay setup
# → sets up personal credentials, creates overlay

Phase-to-Artifact Map

Phase	Artifact
configure	`~/.config/claude-overlay/config.json`
setup	`.claude/settings.local.json` (overlay keys added), `.mcp.json` (tavily/duckduckgo added)
disable	`.claude/settings.local.json` (overlay keys removed)
enable	`.claude/settings.local.json` (overlay keys merged back)
export	stdout (sanitized JSON)

Approval Gates

None — all operations are automatic. setup --dry-run previews without writing.

Memory Context

claude-overlay — Memory & Context

State Storage

claude-overlay uses file-based state:

File	Purpose
`~/.config/claude-overlay/config.json`	Provider credentials (user-global)
`.claude/provider-overlay.json`	Per-project overlay state (what overlay manages)
`.claude/settings.local.json`	Effective project Claude Code config (partially managed)
`.mcp.json`	Effective project MCP config (partially managed)

Overlay State Tracking

.claude/provider-overlay.json stores the saved overlay keys — what was added and its source values — enabling enable to restore exactly what disable removed without data loss.

Session State

None — claude-overlay is stateless at session level. It writes config files that Claude Code reads; it does not track Claude Code sessions.

Context Compaction

Not applicable — claude-overlay does not interact with AI context windows.

The export command produces a sanitized JSON where secrets are replaced with env:VARIABLE_NAME references. Team members import this file and provide their own credentials, enabling config sharing without credential leakage.

Legacy Path Migration

The tool handles migration from earlier versions:

LEGACY_SETTINGS_OFF = .claude/settings.local.json.disabled (old disable mechanism)
LEGACY_MCP_OFF = .mcp.json.disabled
LEGACY_OVERLAY = .claude/databricks-overlay.json (old Databricks-specific path)

Legacy paths are auto-migrated to the new format.

Orchestration

claude-overlay — Orchestration

Multi-Agent Pattern

None — claude-overlay is a configuration tool, not an agent orchestrator.

Orchestration Pattern

none

Execution Mode

one-shot — each command runs and exits.

Isolation Mechanism

none — modifies project-level config files.

Multi-Model Usage

Yes (it enables it) — the primary purpose of claude-overlay is to route Claude Code to a different model endpoint. But it doesn't orchestrate multi-model workflows; it configures which single model endpoint the project uses.

Multi-Provider Switching

claude-overlay configure   # add Databricks
claude-overlay configure   # add OpenRouter
claude-overlay switch      # interactive: pick which to use

This is sequential single-provider configuration, not concurrent multi-provider routing.

Consensus Mechanism

None.

Prompt Chaining

None.

Cross-Tool Portability

Low — specifically targets Claude Code's project-level configuration format (.claude/settings.local.json, .mcp.json). Not applicable to other AI tools.

MCP Configuration

claude-overlay configures external MCP servers (Tavily, DuckDuckGo) in .mcp.json rather than shipping its own MCP server. This allows Claude Code to use web search through these MCP providers when native WebSearch is unavailable.

Ui Cli Surface

claude-overlay — UI & CLI Surface

CLI Binary

Binary name: claude-overlay
Is thin wrapper: No — full bash + Python runtime
Install: Homebrew (brew install claude-overlay) or curl installer

claude-overlay configure              # Set up provider credentials
claude-overlay setup                  # Create overlay in current project
claude-overlay setup --dry-run        # Preview without writing
claude-overlay disable                # Remove overlay keys
claude-overlay enable                 # Restore overlay keys
claude-overlay status                 # Show current project state
claude-overlay switch [provider]      # Switch active provider
claude-overlay export                 # Export config (stdout, secrets sanitized)
claude-overlay import <file>          # Import shared config
claude-overlay doctor                 # Health check
claude-overlay self-update            # Update to latest release
claude-overlay --version              # Print version

Local UI

None — terminal-only with color output (colored bash using ANSI escape codes).

Status Output Style

Claude Overlay — Project Status
/home/user/my-project

  Provider       ENABLED
  Model          databricks-claude-opus-4-7
  ...

Uses ok() (green checkmark), info() (blue arrow), warn() (yellow), err() (red) visual indicators.

Debug Mode

CLAUDE_OVERLAY_DEBUG=1 claude-overlay setup

Enables verbose debug output on stderr.

Shell Completions

bash, zsh, and fish completions in completions/ directory
Auto-completion for subcommands and provider names

MCP Server

None — claude-overlay configures external MCP servers (Tavily, DuckDuckGo) rather than hosting its own.

IDE Integration

None — operates at the project config layer, not the IDE layer.

Observability

doctor command validates full setup health: config file, env vars, project setup, MCP availability
status command shows complete project state with managed vs. unmanaged key separation
Debug mode (CLAUDE_OVERLAY_DEBUG=1) traces all operations

Related frameworks

same archetype · same primary tool · same memory type

BMAD-METHOD ★ 48k

A4 Markdown scaffold

Provides a full agile delivery lifecycle with named expert-persona AI collaborators that elicit the human's best thinking rather…

Agent OS ★ 4.6k

A4 Markdown scaffold

Extracts implicit codebase conventions into token-efficient markdown standards files and injects them selectively into AI agent…

Claude Conductor ★ 367

A4 Markdown scaffold

Gives Claude Code a persistent, cross-linked, auto-analyzed documentation system so it retains codebase context across sessions.

Spec-Driver (Greenfield Spec-Driven Development) ★ 25

A4 Markdown scaffold

Prevents spec rot in AI-assisted development by making implementation changes flow back into evergreen, authoritative specs via…

Anthropic Knowledge Work Plugins ★ 16k

A4 Markdown scaffold

Role-specialized plugin bundles with live MCP connectors that turn Claude into a domain expert for enterprise knowledge workers.

Codex Integration for Claude Code (skill-codex) ★ 1.3k

A4 Markdown scaffold

Single Claude Code skill that handles Codex CLI invocation correctly (stdin blocking, thinking token suppression, session resume)…

Distribution

Type: bash-script-bundle
License: MIT
Install: one-liner
Version: 0.3.0

Surfaces

CLI binary: claude-overlay
CLI subcmds: 12
Local UI: No
Tech stack: none

Components

Commands: 0
Skills: 0
Subagents: 0
Hooks: 0
MCP servers: 0
MCP tools: 0
Scripts: 2
Templates: 0

Workflow

Phases: 4
Approval gates: 0
Spec format: none
Spec storage: none
Delta or full: none

Orchestration

Multi-agent: No
Pattern: none
Max concurrent: 0
Isolation: none
Consensus: none
Prompt chaining: No

Multi-model

Multi-model: No
BYOK: Yes
Modal: text

Execution

Mode: one-shot
Crash recovery: No
Compaction: No
Session handoff: No
Streaming: No

Memory

Type: file-based
Persistence: project
Search: none
State files: 4 files

Quality

TDD: No
TDD mechanism: none
Self-review: none

Git / Observability

Auto commit: No
Auto PR: No
Auto merge: No
Worktree/feat: No
Audit log: No
Audit format: none
Replay: No

Tools

Primary: claude-code
Targets: 1
Portability: low

Signals

Stars: 2
Last commit: 2026-05-14
Contributors: 1
Maintainer: active
Quality score: 0/10

Summary

claude-overlay — Summary

Overview

claude-overlay — Overview

Origin

Problem Solved

Design Principle

Key Technical Pattern: Surgical Config Management

Use Cases

Implementation Approach

Architecture

claude-overlay — Architecture

Distribution

Install Methods

Directory Tree

Config Files

Target Files Written/Modified

Architecture: Bash + Python Split

Provider Support

MCP Web Search Replacement

Components

claude-overlay — Components

CLI Commands (12 subcommands)

Python Engine Operations

Shell Completions

What Gets Preserved (Disable/Enable Invariant)

No Hooks, No Skills, No MCP (Own)

Prompts

claude-overlay — Prompts

Excerpt 1 — Generated settings.local.json (Overlay Active)

Excerpt 2 — Generated .mcp.json (Overlay Active)

Excerpt 3 — Status Output (Generated by claude-overlay status)

Uniqueness

claude-overlay — Uniqueness

differs_from_seeds

Positioning

Observable Failure Modes

Workflow

claude-overlay — Workflow

Initial Setup Workflow

Daily Toggle Workflow

Multi-Provider Workflow

Team Sharing Workflow

Phase-to-Artifact Map

Approval Gates

Memory Context

claude-overlay — Memory & Context

State Storage

Overlay State Tracking

Session State

Context Compaction

Cross-Machine Sharing

Legacy Path Migration

Orchestration

claude-overlay — Orchestration

Multi-Agent Pattern

Orchestration Pattern

Execution Mode

Isolation Mechanism

Multi-Model Usage

Multi-Provider Switching

Consensus Mechanism

Prompt Chaining

Cross-Tool Portability

MCP Configuration

Ui Cli Surface

claude-overlay — UI & CLI Surface

CLI Binary

Local UI

Status Output Style

Debug Mode

Shell Completions

MCP Server

IDE Integration

Observability

Related frameworks

Excerpt 3 — Status Output (Generated by `claude-overlay status`)