autocache: 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

Autocache is an intelligent proxy server for the Anthropic Claude API that automatically injects cache-control fields into requests to reduce costs by up to 90% and latency by up to 85%. It acts as a drop-in replacement proxy that intelligently places cache breakpoints based on token analysis and ROI calculations.

Build and Test Commands

Build

go build -o autocache ./cmd/autocache

Run

# Start with defaults
./autocache

# With custom configuration
CACHE_STRATEGY=aggressive LOG_LEVEL=debug ./autocache

# Using Docker
docker-compose up -d

Run Tests

# Run all unit tests
go test ./... -v

# Run unit tests with coverage
go test ./... -cover

# Run real API tests (requires ANTHROPIC_API_KEY in .env)
./test_real.sh

# Run specific test files
go test -v -run TestCacheInjector

Development

# Run with debug logging
LOG_LEVEL=debug ./autocache

# Run with specific strategy
CACHE_STRATEGY=conservative ./autocache

# Check health
curl http://localhost:8080/health

# Check metrics
curl http://localhost:8080/metrics

Architecture

Project Structure

autocache-gh/
├── cmd/
│   └── autocache/
│       └── main.go                    # Entry point
├── internal/
│   ├── types/                         # Shared types and models
│   │   └── models.go
│   ├── config/                        # Configuration
│   │   └── config.go
│   ├── tokenizer/                     # Token counting
│   │   ├── tokenizer.go              # Interface + heuristic impl
│   │   ├── offline_tokenizer.go      # Embedded tokenizer
│   │   ├── real_tokenizer.go         # API-based tokenizer
│   │   └── anthropic_real_tokenizer.go
│   ├── pricing/                       # Cost calculations
│   │   └── pricing.go
│   ├── client/                        # Anthropic API client
│   │   └── anthropic.go
│   ├── cache/                         # Cache injection logic
│   │   └── injector.go
│   └── server/                        # HTTP server
│       └── handler.go
└── test_fixtures.go                   # Test helpers