🌕 LunaRoute

         ___---___
      .--         --.
    ./   ()      .-. \.
   /   o    .   (   )  \
  / .            '-'    \    _                      ____             _
 | ()    .  O         .  |  | |   _   _ _ __   __ _|  _ \ ___  _   _| |_ ___
|                         | | |  | | | | '_ \ / _` | |_) / _ \| | | | __/ _ \
|    o           ()       | | |__| |_| | | | | (_| |  _ < (_) | |_| | ||  __/
|       .--.          O   | |_____\__,_|_| |_|\__,_|_| \_\___/ \__,_|\__\___|
 | .   |    |            |
  \    `.__.'    o   .  /
   \                   /
    `\  o    ()      /
      `--___   ___--'
            ---

Your AI Coding Assistant's Best Friend

A blazing-fast local proxy for AI coding assistants that gives you complete visibility into every LLM interaction. Zero configuration, sub-millisecond overhead, and powerful debugging capabilities.

⚡ Quick Start - Literally One Command

eval $(lunaroute-server env)

That's it! This single command:

• ✅ Starts LunaRoute server in the background
• ✅ Configures Claude Code (sets ANTHROPIC_BASE_URL)
• ✅ Configures Codex CLI (sets OPENAI_BASE_URL)
• ✅ Accepts both OpenAI and Anthropic formats simultaneously
• ✅ Tracks every token, tool call, and conversation

Start coding with your AI assistant immediately - both APIs are ready to use!

---

Alternative: Manual Setup

If you prefer to run the server manually:

# Terminal 1: Start the server
lunaroute-server

# Terminal 2: Point your AI tools to it
export ANTHROPIC_BASE_URL=http://localhost:8081  # For Claude Code
export OPENAI_BASE_URL=http://localhost:8081/v1  # For Codex CLI

That's it. No API keys to configure, no YAML files to write, nothing. LunaRoute automatically:

• ✅ Accepts both OpenAI and Anthropic formats simultaneously
• ⚡ Runs in dual passthrough mode (zero normalization overhead)
• 🔑 Uses your existing API keys (from env vars or client headers)
• 📊 Tracks every token, tool call, and conversation
• 🎯 Routes requests based on model prefix (gpt-* → OpenAI, claude-* → Anthropic)

---

🎯 Why LunaRoute?

See Everything Your AI Does

Stop flying blind. LunaRoute records every interaction with zero configuration:

• 🔍 Debug AI conversations - See exactly what your assistant sends and receives
• 💰 Track token usage - Input, output, and thinking tokens broken down by session
• 🔧 Analyze tool performance - Which tools are slow? Which get used most?
• 📊 Measure overhead - Is it the LLM or your code that's slow?
• 🔎 Search past sessions - "How did the AI solve that bug last week?"

Zero Configuration, Maximum Power

# Literally just one command
eval $(lunaroute-server env)

What you get instantly:

• ⚡ Dual API support - OpenAI /v1/chat/completions + Anthropic /v1/messages
• 🚀 Passthrough mode - Sub-millisecond overhead, 100% API fidelity
• 🔑 Automatic auth - Uses environment variables or client-provided keys
• 📊 Session tracking - SQLite database + JSONL logs for deep analysis
• 🎨 Web UI - Browse sessions at http://localhost:8082
• 🔄 Background server - Detached process, continues running even after terminal closes

How it works:

$ lunaroute-server env
export ANTHROPIC_BASE_URL=http://127.0.0.1:8081
export OPENAI_BASE_URL=http://127.0.0.1:8081/v1
# LunaRoute server started on http://127.0.0.1:8081
# Web UI available at http://127.0.0.1:8082

$ eval $(lunaroute-server env)  # Sets env vars and starts server

$ # Now use your AI tools normally - they're automatically configured!

Privacy & Performance

• 🔒 PII redaction - Auto-detect and redact emails, SSN, credit cards, phone numbers
• ⚡ 0.1-0.2ms overhead - Sub-millisecond proxy latency in passthrough mode
• 🛡️ Zero trust storage - Redact before hitting disk, not after
• 🔐 Local first - All data stays on your machine

---

📦 Installation

Option 1: Download Binary (Recommended)

Download the latest release for your platform from GitHub Releases:

# Linux/macOS: Extract and run
tar -xzf lunaroute-server-*.tar.gz
chmod +x lunaroute-server

# Optional: Add to PATH for global access
sudo mv lunaroute-server /usr/local/bin/

# Start using it immediately!
eval $(lunaroute-server env)

Option 2: Build from Source

git clone https://github.com/erans/lunaroute.git
cd lunaroute
cargo build --release --package lunaroute-server

# Binary location: target/release/lunaroute-server

# Start using it!
eval $(./target/release/lunaroute-server env)

---

🚀 Usage

Recommended: One-Command Setup

The fastest way to get started - automatically starts server and configures your shell:

# One command does everything!
eval $(lunaroute-server env)

# Now use your AI tools - they're automatically configured
# Both Claude Code and Codex CLI work immediately

What happens:

• Server starts in background on port 8081
• ANTHROPIC_BASE_URL set to http://127.0.0.1:8081
• OPENAI_BASE_URL set to http://127.0.0.1:8081/v1
• Web UI available at http://127.0.0.1:8082

Custom port:

eval $(lunaroute-server env --port 8090)

Stop the server:

pkill -f "lunaroute-server serve"

---

Alternative: Manual Mode

If you prefer to manage the server yourself:

# Terminal 1: Start LunaRoute
lunaroute-server

# Terminal 2: Configure your shell
export ANTHROPIC_BASE_URL=http://localhost:8081
export OPENAI_BASE_URL=http://localhost:8081/v1

# Now use Claude Code or Codex CLI
# View sessions at http://localhost:8082

What you get out of the box:

✓ OpenAI provider enabled (no API key - will use client auth)
✓ Anthropic provider enabled (no API key - will use client auth)
📡 API dialect: Both (OpenAI + Anthropic)
⚡ Dual passthrough mode: OpenAI→OpenAI + Anthropic→Anthropic (no normalization)
   - gpt-* models    → OpenAI provider (passthrough)
   - claude-* models → Anthropic provider (passthrough)
🚀 Bypass enabled for unknown API paths
📊 Session recording enabled (SQLite + JSONL)
🎨 Web UI available at http://localhost:8082

With Custom Configuration

Need more control? Use a config file:

# Save as config.yaml
host: "127.0.0.1"
port: 8081
api_dialect: "both"  # Already the default!

providers:
  openai:
    enabled: true
    base_url: "https://api.openai.com/v1"  # Or use ChatGPT backend
    # api_key: "sk-..."  # Optional: defaults to OPENAI_API_KEY env var

  anthropic:
    enabled: true
    # api_key: "sk-ant-..."  # Optional: defaults to ANTHROPIC_API_KEY env var

session_recording:
  enabled: true
  sqlite:
    enabled: true
    path: "~/.lunaroute/sessions.db"
  jsonl:
    enabled: true
    directory: "~/.lunaroute/sessions"
    retention:
      max_age_days: 30
      max_size_mb: 1024

ui:
  enabled: true
  host: "127.0.0.1"
  port: 8082

lunaroute-server --config config.yaml

---

✨ Key Features

🎯 Dual-Dialect Passthrough (Default)

LunaRoute accepts both OpenAI and Anthropic formats simultaneously with zero normalization:

• OpenAI format at /v1/chat/completions → routes to OpenAI
• Anthropic format at /v1/messages → routes to Anthropic
• Zero overhead - ~0.1-0.2ms added latency
• 100% API fidelity - preserves extended thinking, all response fields
• No normalization - direct passthrough to native API

📊 Comprehensive Session Recording

Track everything that matters with dual storage:

SQLite Database - Fast queries and analytics:

SELECT model_used, COUNT(*), SUM(input_tokens), SUM(output_tokens)
FROM sessions
WHERE started_at > datetime('now', '-7 days')
GROUP BY model_used;

JSONL Logs - Human-readable, full request/response data:

# Watch live sessions
tail -f ~/.lunaroute/sessions/$(date +%Y-%m-%d)/session_*.jsonl | jq

# Search for specific content
grep -r "TypeError" ~/.lunaroute/sessions/

📈 Session Statistics

Get detailed breakdowns on shutdown or via API:

📊 Session Statistics Summary
═══════════════════════════════════════════════════════════════

Session: 550e8400-e29b-41d4-a716-446655440000
  Requests:        5
  Input tokens:    2,450
  Output tokens:   5,830
  Thinking tokens: 1,200
  Total tokens:    9,480

  Tool usage:
    Read:  12 calls (avg 45ms)
    Write: 8 calls (avg 120ms)
    Bash:  3 calls (avg 850ms)

  Performance:
    Avg response time: 2.3s
    Proxy overhead:    12ms total (0.5%)
    Provider latency:  2.288s (99.5%)

💰 Estimated cost: $0.14 USD

🔒 PII Detection & Redaction

Protect sensitive data automatically before it hits disk:

session_recording:
  pii:
    enabled: true
    detect_email: true
    detect_phone: true
    detect_ssn: true
    detect_credit_card: true
    redaction_mode: "tokenize"  # mask, remove, tokenize, or partial

Before: My email is john.doe@example.com and SSN is 123-45-6789 After: My email is [EMAIL:a3f8e9d2] and SSN is [SSN:7b2c4f1a]

📊 Prometheus Metrics

24 metric types at /metrics:

• Request rates (total, success, failure)
• Latency histograms (P50, P95, P99)
• Token usage (input/output/thinking)
• Tool call statistics
• Streaming performance

Perfect for Grafana dashboards.

🎨 Web UI

Built-in web interface for browsing sessions:

# Automatically available at http://localhost:8082
lunaroute-server

Features:

• 📊 Dashboard with filtering and search
• 🔍 Session details with timeline view
• 📄 Raw JSON inspection
• 📈 Token usage and performance analytics

---

🔧 Advanced Configuration

Quick Setup with env Command

The env command starts the server in the background and outputs shell commands to configure your environment:

# Basic usage - starts server on default port 8081
eval $(lunaroute-server env)

# Custom port
eval $(lunaroute-server env --port 8090)

# Custom host and por