llmio: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

LLMIO is a Go-based LLM proxy service that provides unified API access to multiple language model providers (OpenAI, Anthropic, Gemini) with intelligent load balancing and a React-based management interface.

Key Commands

Backend Development

# Run the application (formats, tidies, creates db dir, then starts)
TOKEN=<YOUR_TOKEN> make run

# Build the binary
go build -o llmio .

# Run all tests
go test ./...

# Run a single package's tests
go test ./balancers/...

# Run a single test
go test -run TestWeightedList ./balancers/

# Format code
go fmt ./...

# Tidy dependencies
go mod tidy

Frontend Development

cd webui

# Install dependencies
pnpm install

# Run development server (proxies /api to localhost:7070)
pnpm run dev

# Build for production
pnpm run build

# Build frontend and embed into Go binary
make webui

# Run linting
pnpm run lint

Docker Development

docker build -t llmio .
docker run -p 7070:7070 -e TOKEN=your_token llmio
docker-compose up -d

Architecture Overview

Backend Structure

The application follows a layered architecture:

1. Handlers (/handler) — HTTP request processing and routing. Each API area gets its own file: chat.go (LLM completion endpoints), api.go (management APIs), models.go (model CRUD), auth_keys.go (API key management), event_logging.go (Claude Code event ingestion), stats.go (analytics aggregation), count_tokens.go (Anthropic token counting), test.go (provider connectivity and capability tests), version.go. Static file serving is not a handler: the React build is embedded in main.go via //go:embed webui/dist.

2. Services (/service) — Business logic layer.

   • chat.go — Core chat processing: balancing, request dispatch, retry orchestration
   • before.go — Pre-processing pipeline that parses incoming requests to detect capabilities (tool calling, structured output, image input) for routing decisions. Has per-provider-style parsers (OpenAI, OpenAIRes, Anthropic, Gemini)
   • models.go — Provider/model association management
   • auth.go — AuthKey management
   • process.go — Request processing utilities
   • provider_error_matcher.go — Error classification for rate limits and failures
   • log_cleanup.go — Scheduled log retention cleanup