pkg

Documentation

Overview

Package cli holds the application struct that service.MainCmd parses CLI args into, plus the Run entry-point that delegates to the injected server factory. The factory itself lives in pkg/factory; this package is import-free of factory to keep the dependency direction (main -> factory -> ...) intact.

Package config loads and validates the claude-code-router YAML configuration. The config describes:

• listed providers (each: upstream URL, optional token, list of model-name glob patterns)
• which provider to route to when no glob matches (default_provider)

Routing is per-request: the model-router inspects the JSON body's `model` field and forwards to the matching provider's reverse proxy.

Index

• func FindConfigDir(toolName string) string
• type App
  • func NewApp(serverFactory ServerFactory) *App
  • func (a *App) Run(ctx context.Context) error
• type Config
  • func Load(ctx context.Context, rawPath string) (*Config, error)
  • func (c *Config) Validate(ctx context.Context) error
• type Provider
• type Router
• type ServerFactory

Functions

func FindConfigDir

func FindConfigDir(toolName string) string

FindConfigDir returns the config directory for toolName using XDG conventions with legacy dotfile fallback. Priority:

1. ~/.config/<toolName>/ if it exists
2. ~/.<toolName>/ if it exists
3. ~/.config/<toolName>/ (XDG default when neither exists — new installs land in the XDG location from the start)

Deliberately does NOT use os.UserConfigDir() — on macOS that resolves to ~/Library/Application Support, which is not this project's XDG convention (~/.config/<tool>/ on every platform, matching task-watcher and vault-ui).

Types

type App

type App struct {
	Listen     string `arg:"listen"      default:"127.0.0.1:8788" env:"LISTEN"      required:"true"  usage:"address to listen to"`
	ConfigPath string `` /* 267-byte string literal not displayed */
	// contains filtered or unexported fields
}

App is the application wired by main and parsed by service.MainCmd's argument tagger. Exported fields with tags are CLI args; unexported fields are dependencies injected by main.

func NewApp

func NewApp(serverFactory ServerFactory) *App

NewApp constructs the App with the server factory injected.

func (*App) Run

func (a *App) Run(ctx context.Context) error

Run is invoked by service.MainCmd after argument parsing.

type Config

type Config struct {
	Router    Router              `yaml:"router"`
	Providers map[string]Provider `yaml:"providers"`
	// Aliases maps a short operator-typed model name to the full
	// model string the upstream expects. Resolved single-hop before
	// glob-routing: a request body `{"model":"qwen"}` becomes
	// `{"model":"qwen3.6:35b-a3b-coding-nvfp4"}` before the router
	// walks providers' models globs. Nil / empty map = no-op.
	Aliases map[string]string `yaml:"aliases,omitempty"`
	// Trace, when true, enables per-request trace logging for /v1/*
	// requests: every request writes one JSON file capturing the full
	// request and response to ~/.claude-code-router/trace/. When false
	// (or absent), no trace files are written and no trace middleware
	// is allocated on the request hot path. Read once at Load; a
	// restart applies it.
	Trace bool `yaml:"trace,omitempty"`
}

Config is the parsed YAML root.

func Load

func Load(ctx context.Context, rawPath string) (*Config, error)

Load reads, parses, and validates the config at path. Tilde-prefix (~/) is expanded to the user's home directory.

func (*Config) Validate

func (c *Config) Validate(ctx context.Context) error

Validate checks that the parsed config is internally consistent.

type Provider

type Provider struct {
	// Upstream is the base URL, e.g. https://api.anthropic.com.
	Upstream string `yaml:"upstream"`
	// Token, if set, replaces the client's Authorization header with
	// "Bearer <Token>". If empty, the client's Authorization is
	// forwarded verbatim — used for the subscription-OAuth case.
	Token string `yaml:"token,omitempty"`
	// Models is the list of glob patterns (filepath.Match syntax) the
	// router uses to match request body's `model` field. Examples:
	// "claude-opus-*", "MiniMax-*", "qwen*".
	Models []string `yaml:"models"`
}

Provider describes one upstream LLM API.

type Router

type Router struct {
	// DefaultProvider is the provider key used when no model glob matches.
	// Must reference a key in Providers; validated on Load.
	DefaultProvider string `yaml:"default_provider"`
}

Router holds router-wide settings.

type ServerFactory

type ServerFactory func(ctx context.Context, listen, configPath string) (librun.Func, error)

ServerFactory is the dep cli requires to start the HTTP listener. Satisfied by factory.CreateServer. Returns the run.Func + any startup error (config load, validation, etc.).