Tresor: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with the Tresor codebase.

Project Overview

Tresor is a single-binary LLM gateway for switching providers at scale with one click. It sits between client applications and LLM providers (OpenAI, Anthropic, etc.), transforming requests and responses via a configurable plugin pipeline. The binary serves dual roles: a daemon (long-running HTTP gateway + admin API) and a CLI client for controlling the daemon.

See PLAN.md for the full architectural design.

Configuration

Tresor is configured entirely via a single YAML config file. See config.example.yaml for a complete example.

Config File Locations (auto-detected in order)

1. Path specified by --config flag
2. ./config.yaml in current directory
3. $HOME/.tresor.yaml

To get started: cp config.example.yaml config.yaml, then edit as needed.

YAML Structure

bind_addr: "127.0.0.1:11510"         # TCP address for gateway
socket_path: "/tmp/tresor.sock"  # Optional Unix socket (admin only)
db_path: "./tresor.db"          # SQLite database path
admin_password: "secret"        # Optional: admin password for cookie-based session auth
proxy_api_keys:                 # Optional: require clients to authenticate proxy requests
  - sk-proxy-123
proxy_mode: "auto"              # Outbound proxy: auto, env, windows, none
default_tab: "downstreams"      # Dashboard tab on load (values: downstreams, aliases, rules, settings, about)
log_level: "info"               # Request logging verbosity: debug, info, warn, error
capture_payloads: false         # Capture raw request/response bodies for the Logs inspector (claude-tap-style)
icon_cache_dir: "~/.config/tresor/tresor-icons/"  # Cache directory for model icon SVGs (~ expands to home dir)
retry_on_empty: false           # Automatically retry requests when the downstream returns an empty response (HTTP 200 but no content)

downstreams:                    # LLM provider endpoints
  - id: my-provider
    name: My Provider
    base_url: https://api.example.com
    api_key: sk-...
    api_formats: [openai]       # API format(s): openai, anthropic, openai_responses, gemini
    output_model_ids:           # Models this downstream can handle (required for forwarding)
      - gpt-4o

rules:                          # Routing rules (OPTIONAL — only for transforms)
  - id: my-rule
    name: Chat Rule
    pattern_path: /v1/chat/completions
    pattern_model: gpt-4o       # Optional model filter
    match_format: [openai]      # Match input request format
    match_downstream_format: [anthropic]  # Match downstream API format
    match_downstreams: [my-provider]      # Match specific downstreams
    pipeline_config:            # Transformation steps
      - plugin_id: openai2anthropic
    is_enabled: true

aliases:                        # Model name mappings (hot-switchable, ordered by array position)
  - input_model_id: gpt-4o
    is_regex: false             # Treat input_model_id as regex (group-level, optional)
    options:
      - id: alias-gpt4o-anthropic
        downstream_id: my-provider
        output_model_id: claude-sonnet-4-20250514