llm-debugger

Debug and log LLM API requests with streaming support.

Quick Start

# Start proxy to OpenAI
npx llm-debugger@latest --target https://api.openai.com

# Start proxy to Anthropic
npx llm-debugger@latest --target https://api.anthropic.com

Usage

Point your LLM client to the proxy instead of the API directly:

# Instead of: https://api.openai.com/v1/chat/completions
# Use:        http://localhost:8000/v1/chat/completions

View logged requests at http://localhost:8000/__viewer__

Routes

Route	Description
/*	Forwards requests to target API
/__viewer__	Web UI to inspect logged requests

Per-request overrides

Two headers let you override proxy behavior for a single request without restarting:

Header	Effect
llm-debugger-url: <url>	Override the upstream target URL (full URL only)
llm-debugger-cache: true|false	Force snapshot cache on or off for this request

Both headers are stripped before forwarding and never written into snapshots.

Example:

curl http://localhost:8000/v1/chat/completions \
  -H 'Authorization: Bearer sk-xxx' \
  -H 'llm-debugger-url: https://api.openai.com' \
  -H 'Content-Type: application/json' \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"hi"}]}'

Programmatic API

Run the proxy from your own scripts. No config file is read or written — pass everything as options.

import { startProxy } from 'llm-debugger';

const proxy = await startProxy({
  target: 'https://api.openai.com',
});

console.log(proxy.url);  // http://localhost:8000

// ...point your client at proxy.url and run your code...

await proxy.stop();

Options

Option	Default	Description
target	—	Upstream URL.
host	localhost	Bind host.
port	8000-8100	Single port or range; first free port wins.
cache	true	Enable snapshot replay cache.
snapshotDir	<cwd>/.snapshots	Where snapshots are stored.
ignoreRoutes	[]	Glob patterns for paths to skip (no proxy, no log).
hideFromViewer	[]	Glob patterns for paths to log but hide from the viewer UI.
enabled	true	Toggle request logging (proxy still works when off).
maxLogs	100	Log retention before rotation; 0 disables rotation.
logsDir	<cwd>/.llm-debugger/logs	Where logs are written.
cwd	process.cwd()	Used as the base for logsDir and snapshotDir defaults.

Return value

{
  url: string;          // e.g. "http://localhost:8000"
  port: number;
  host: string;
  server: http.Server;  // raw Node server, for advanced use
  stop: () => Promise<void>;
}

Configuration

When running via the CLI, config lives at ~/.llm-debugger/config.yaml and logs at ~/.llm-debugger/logs. Override the base directory with:

• LLM_DEBUGGER_HOME - Base directory

Snapshot cache

When the cache is on, the proxy records each upstream response to a JSON file under <cwd>/.snapshots/ and replays it on a subsequent matching request. The cache key is sha256(method + url + body) truncated to 12 hex chars.

Snapshots are organised as <snapshot_dir>/<sanitized-host-and-path>/<model>/<hash>.json. Model falls back to default when the request has no model field.

Toggle defaults via config:

llm-debugger config set cache true
llm-debugger config set snapshot_dir /path/to/snapshots

Override per request with the llm-debugger-cache header. Browse snapshots in the viewer at http://localhost:8000/__viewer__/snapshots.

Config Commands

npx llm-debugger@latest config show              # Display current config
npx llm-debugger@latest config edit              # Open config in editor
npx llm-debugger@latest config set <key> <value> # Set enabled, max_logs, cache, snapshot_dir

Only true and false strings are coerced to booleans; other strings such as yes are stored unchanged.

License

MIT