ccflare 🛡️

Track Every Request. Go Low-Level. Never Hit Rate Limits Again.

The ultimate Claude API proxy with intelligent load balancing across multiple accounts. Full visibility into every request, response, and rate limit.

video_compressed.mp4

Why ccflare?

• 🚀 Zero Rate Limit Errors - Automatically distribute requests across multiple accounts
• 📊 Request-Level Analytics - Track latency, token usage, and costs in real-time
• 🔍 Deep Debugging - Full request/response logging and error traces
• ⚡ <10ms Overhead - Minimal performance impact on your API calls
• 💸 Free & Open Source - Run it yourself, modify it, own your infrastructure

Quick Start

# Clone and install
git clone https://github.com/snipeship/ccflare
cd ccflare
bun install

# Start ccflare (TUI + Server)
bun run ccflare

# Configure Claude SDK
export ANTHROPIC_BASE_URL=http://localhost:8080

Run with Docker

# Build the image (ships with dashboard assets prebuilt)
docker build -t ccflare .

# Start the server inside Docker
docker run -d \
  --name ccflare \
  -p 8080:8080 \
  -v ccflare_data:/data \
  -e PORT=8080 \
  -e LB_STRATEGY=session \
  ccflare

The container stores configuration and the SQLite database under /data (mapped to ccflare_CONFIG_PATH=/data/config/ccflare.json and ccflare_DB_PATH=/data/storage/ccflare.db). Mount a volume there (shown above) to persist settings between restarts. See docs/deployment.md for compose examples and advanced options (health checks, reverse proxies, custom networks, etc.).

Agent Workspaces & Discovery

ccflare loads agents from Markdown files inside .claude/agents/ folders. To keep your container in sync with projects scattered across Linux, WSL, or Windows:

# One-time automation: scan, capture workspaces, restart container with minimal mounts
bun run agents:setup

# Manual scan if you want to keep the container running
bun run agents:scan -- /host /mnt/c --max-depth 8

• The setup script stops ccflare-dev, launches a helper container with wide mounts, runs the scanner, and restarts ccflare-dev with only the discovered bind mounts plus /data, while sharing a ccflare-workspaces volume that persists /root/.ccflare/workspaces.json between restarts.
• The dashboard now includes a Register Workspace Paths card (Agents tab) so you can add absolute paths on the fly. Behind the scenes it calls POST /api/workspaces (documented in docs/api-http.md).
• For more examples (mount tables, environment variables, troubleshooting) see docs/agent-workspaces.md.

Features

🎯 Intelligent Load Balancing

• Session-based - Maintain conversation context (5hr sessions)

📈 Real-Time Analytics

• Token usage tracking per request
• Response time monitoring
• Rate limit detection and warnings
• Cost estimation and budgeting

🛠️ Developer Tools

• Interactive TUI (bun run ccflare)
• Web dashboard (http://localhost:8080/dashboard)
• CLI for account management
• REST API for automation

🔒 Production Ready

• Automatic failover between accounts
• OAuth token refresh handling
• SQLite database for persistence
• Configurable retry logic

Documentation

Full documentation available in docs/:

• Getting Started
• Architecture
• API Reference
• Configuration
• Load Balancing Strategies

Screenshots

Real-time Dashboard	Request Logs
Analytics & Usage Tracking

Requirements

• Bun >= 1.2.8
• Claude API accounts (Free, Pro, or Team)

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

License

MIT - See LICENSE for details

---

Built with ❤️ for developers who ship