# ⚡ 10-Second Quickstart (Zero Configuration Needed)
pip install omnicache-proxy
omnicache run claude

💡 Why OmniCache?

When autonomous coding agents (Claude Code, Cursor, Aider, Cline) work on your codebase, up to 60%–80% of your token burn and latency goes into repetitive disk and file reads:

• Re-reading package.json, tsconfig.json, directory trees, and lint rules on every single turn.
• Running test suites, git diffs, or bash inspection commands where the underlying code has not changed.
• Paying frontier cloud input prices ($3–$15 per million tokens) and waiting 1,200ms–2,500ms per roundtrip for identical content.

┌────────────────────────┬────────────────────────┬────────────────────────┬────────────────────────┐
│      < 0.1 ms          │        $0.00           │        100%            │        100%            │
│  Tool Replay Latency   │  Cost on Repeat Reads  │  Token Savings on Hits │  Localhost Air-Gapped  │
└────────────────────────┴────────────────────────┴────────────────────────┴────────────────────────┘

The Difference:

How it works: OmniCache sits transparently on 127.0.0.1:8000. It cryptographically fingerprints your local Git tree and workspace file modification times (mtime). If the files haven't changed, the agent receives the exact tool output or cached completion from local SQLite WAL memory in under 0.1ms without touching the internet. The second you edit a file or git commit, affected cache entries are instantly evicted.

📐 Architecture

flowchart TD
    subgraph Client["Developer Coding Workspace"]
        Agent["🤖 AI Coding Agent<br/>(Claude Code / Cursor / Cline / Aider)"]
    end

    subgraph Sidecar["⚡ OmniCache Local Engine (127.0.0.1:8000)"]
        Router["Transparent Interceptor<br/>(Protocol Translator)"]
        
        subgraph MemoryFabric["Deterministic Memory Subsystems"]
            GitCheck{"Git Working Tree<br/>Changed?"}
            L1["L1 Exact Trie Cache<br/>(0.06ms Lookup)"]
            L2["L2 Quantized Vector Cache<br/>(Int8 SIMD Cosine Match)"]
            ToolStore[("SQLite WAL Store<br/>Tool & File Signatures")]
            Compactor["Context Compaction<br/>(Head/Tail Pruning)"]
        end
    end

    subgraph Cloud["Remote Cloud Providers (Only on Cache Miss)"]
        Upstream["Anthropic / OpenAI / Gemini<br/>(1,000ms - 2,500ms Turn)"]
    end

    Agent -->|"ANTHROPIC_BASE_URL<br/>OPENAI_BASE_URL"| Router
    Router --> GitCheck
    GitCheck -->|"Unchanged (Hit)"| ToolStore
    GitCheck -->|"Prompt Re-evaluation"| L1
    L1 -->|"Exact Match"| ToolStore
    L1 -->|"Fuzzy Match"| L2
    ToolStore -->|"Replay in <0.1ms ($0.00)"| Agent
    
    L2 -->|"Cache Miss"| Compactor
    Compactor -->|"Pruned Prompt"| Upstream
    Upstream -->|"Record to SQLite WAL"| ToolStore
    ToolStore -->|"Streaming Response"| Agent

💡 Why OmniCache vs. Native Provider Caching?

Anthropic and OpenAI offer server-side prompt caching, which discounts prefix tokens in the cloud. However, native cloud caching leaves four critical developer gaps unaddressed:

🚀 60-Second Quickstart

1. Install via PyPI

pip install omnicache-proxy

2. Verify Your Environment

omnicache doctor

3. Launch Your Coding Agent (Zero Configuration Changes)

Use the run execution wrapper. It automatically launches the background sidecar, exports loopback environment variables (ANTHROPIC_BASE_URL, OPENAI_BASE_URL, LLM_BASE_URL), and displays a session savings summary when you finish:

# Claude Code:
omnicache run claude

# Cursor IDE:
omnicache run cursor .

# Custom Python agent scripts or runners:
omnicache run -- python my_agent.py

When your session exits, OmniCache renders your verified telemetry ledger:

╭──────────────────────────────────────────────────╮
│ ⚡ OmniCache Session Telemetry                   │
│  - Tokens Saved:       18,450 tokens             │
│  - Avoided Cost:       $0.0554 USD               │
│  - Tool Replays:            14 cached tool calls │
╰──────────────────────────────────────────────────╯

⚡ Verified Performance Benchmarks

Measured on standard commodity ARM/x86 hardware running Python 3.10–3.14:

==================================================================================================
Subsystem                        Est. Upstream Turn   OmniCache Replay   Speedup    Benefit
==================================================================================================
L1 Exact Request Cache           ~450.00 ms (Est.)    0.0609 ms          7,390x     100% Token Savings
L2 FastHash Fuzzy/Near-Duplicate ~450.00 ms (Est.)    1.0232 ms            439x     Fuzzy Subword Match
Agent Tool Replayer (Git-Aware)  ~1,200.00 ms (Est.)  0.3052 ms          3,931x     $0.00 Disk Thrashing
Workspace CI/CD Pre-Warming      Cold Repo Scan       2781.43 ms         2 f/s      Pre-warmed 5 files
==================================================================================================
* Est. Upstream Turn represents typical remote cloud LLM network roundtrips.
  OmniCache Replay columns represent actual locally measured micro-benchmarks on hardware.

Run benchmarks locally anytime:

omnicache benchmark

🤖 Drop-In Agent Support

OmniCache automatically writes native configurations for your preferred developer environment:

# Auto-configure Claude Code, Cursor, Cline, and OpenHands:
omnicache init

# Or preview configuration JSON / TOML snippets without touching disk:
omnicache init --show

# Target a specific assistant:
omnicache init --agent claude
omnicache init --agent cursor
omnicache init --agent cline

Manual Environment Variables

If you prefer configuring your shell manually:

# Claude Code
export ANTHROPIC_BASE_URL="http://127.0.0.1:8000"

# OpenAI SDK & Cursor
export OPENAI_BASE_URL="http://127.0.0.1:8000/v1"
export OPENAI_API_BASE="http://127.0.0.1:8000/v1"

🔌 Model Context Protocol (MCP) Server

OmniCache provides a native, enterprise-ready Model Context Protocol (MCP) server compliant with Anthropic's Connectors Directory Policy. It supports both Local Stdio (omnicache mcp) for desktop workflows and Streamable HTTP (GET/POST /mcp) with Server-Sent Events (SSE), Mcp-Session-Id session tracking, and RFC 8414 / RFC 9728 OAuth 2.0 discovery metadata.

Transports Supported

• Local Stdio Transport: Standard JSON-RPC 2.0 loop via omnicache mcp for Claude Desktop, Claude Code, Cursor, and Cline.
• Streamable HTTP Transport: Hosted/remote endpoint at http://127.0.0.1:8000/mcp with persistent SSE streams (Accept: text/event-stream), protocol version negotiation (2024-11-05), and automated OAuth 2.0 discovery (/.well-known/oauth-authorization-server).

1-Click Install via Smithery

Install directly to Claude Desktop with one command:

npx -y @smithery/cli install omnicache --client claude

Direct Agent Configuration

Claude Code (CLI)

claude mcp add omnicache -- omnicache mcp

Claude Desktop (claude_desktop_config.json) & Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "omnicache": {
      "command": "omnicache",
      "args": ["mcp"],
      "env": {
        "OMNICACHE_ORG_ID": "default"
      }
    }
  }
}

Provided Tools

Example Agent Prompts Exercising MCP Tools

1. omnicache_query: "Check OmniCache to see if we have an optimized SQLite WAL connection pool implementation in Python."
2. omnicache_search: "Search our cached knowledge base for solutions related to OAuth 2.0 token expiration and refresh token rotation."
3. omnicache_store: "Store our standard API rate limiting configuration in OmniCache under the tag 'networking'."

For complete MCP documentation, payloads, and JSON schemas, see mcp/README.md.

📊 Engineering Telemetry Dashboard

OmniCache includes a real-time developer telemetry dashboard:

Engineering Blueprint Dashboard (http://localhost:8000/dashboard)

• Dark Neo-Brutalist Architecture: High-contrast schematic blueprint layout matching the production frontend.
• Single-Frame Mobile KPI Matrix: All 6 core performance and financial metrics visible above the fold on mobile screens without scrolling.
• Twin Telemetry Monitors: Streaming financial savings spline + resolution distribution breakdown (L1 Exact, L2 Semantic, and Git Tool replays).
• Live Sandbox & Upstream Inspection: Test Claude Messages and OpenAI completions in-browser with synthetic PII generation, hot routing, and transparent billing indicators.

🛠️ Command Cheatsheet

🔒 Security & Enterprise Readiness

• Strict Localhost Binding: By default, OmniCache binds strictly to loopback (127.0.0.1:8000), refusing to expose unauthenticated endpoints to external networks.
• Salted HMAC-SHA256 Tokenization: The built-in PrivacyShield scrubs sensitive developer credentials (emails, API keys, private tokens) locally before optional upstream transmission.
• Cryptographic Multi-Tenancy: Complete tenant isolation via org_id and OMNICACHE_ORG_ID environment variables.
• SOC2-Ready Audit Logging: Structured JSONL audit trails recording all MCP tool executions, durations, and statuses written to ~/.omnicache/mcp_audit.jsonl.
• Zero Remote Telemetry: All embeddings, SQLite WAL database writes, and telemetry aggregations execute strictly in-process. No code or prompt data is ever phoned home to external servers.
• For security disclosures and guidelines, see SECURITY.md.
• For complete data handling, retention policies, and user purge rights under Anthropic Directory Policy, see PRIVACY.md.

🐳 Docker & Container Deployment

OmniCache provides a hardened container image with fail-closed security invariants:

# REQUIRED: Pass ADMIN_API_KEY at runtime (do not bake keys into image layers)
docker run -d \
  -p 8000:8000 \
  -e ADMIN_API_KEY="your-secure-random-admin-key" \
  omnicache-proxy:latest

# Or launch with docker-compose (includes Redis + automated healthchecks)
docker-compose up -d

📄 Documentation

• 📜 Privacy Policy & Full Policy Document
• 📖 Architecture Deep Dive
• 🤖 Agent Integrations Guide (Claude Code, Cursor, Cline)
• 📡 API Reference
• 🔬 Independent Empirical Audit Report
• ❓ Troubleshooting & FAQ

⚖️ License

Distributed under the Functional Source License, Version 1.1 (FSL-1.1-MIT).
Copyright (c) 2026 Rajiv Prasad.

Free for developers and internal organizational use; prevents third-party commercial cloud hosting/proxy competition; converts automatically to standard MIT License after two years. See LICENSE for full legal terms.