Configuration

Environment variables

Variable	Default	Description
FRONTEND_DEBUGGER_PROJECT_ROOT	process.cwd()	Root directory for baselines, replays, and file operations
FRONTEND_DEBUGGER_ALL_TOOLS	0	Set to 1 to register all 46 tools at startup
FRONTEND_DEBUGGER_SNAPSHOT_DIR	—	If set, image-returning tools write PNGs here and return file paths instead of inline base64 — saves MCP context tokens
FRONTEND_DEBUGGER_AI_PROVIDER	anthropic	LLM backend for audit_explain_ai: anthropic or openai
ANTHROPIC_API_KEY	—	Key for the Anthropic provider
OPENAI_API_KEY	—	Key for the OpenAI-compatible provider (omit for keyless local servers)
OPENAI_BASE_URL	https://api.openai.com/v1	OpenAI-compatible endpoint — set to a local server (Ollama http://localhost:11434/v1, vLLM, LM Studio) to run open-source models

fd.config.json

The CLI and CI runner read configuration from fd.config.json in the project root:

{
  "chrome": {
    "port": 9222,
    "host": "localhost"
  },
  "tokensFile": "design-tokens.json",
  "baseline": "homepage",
  "skip": []
}

Field	Type	Description
chrome.port	number	Chrome debugging port
chrome.host	string	Chrome host
tokensFile	string	Path to design token definitions
baseline	string	Default baseline name for visual diffs
skip	string[]	Checks to skip (a11y, contrast, aria)

Design token format

The tokensFile should be a JSON file mapping token names to values:

{
  "color-primary": "#7c3aed",
  "color-secondary": "#2563eb",
  "font-size-base": "16px",
  "spacing-md": "16px",
  "border-radius-lg": "12px"
}

The token audit compares computed CSS values on the page against these definitions and flags drift with delta-E color distance calculations.

Chrome setup

Frontend Debugger connects to Chrome via the DevTools Protocol. Chrome must be launched with remote debugging enabled:

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222

# Linux
google-chrome --remote-debugging-port=9222

# Docker (headless)
google-chrome --headless --remote-debugging-port=9222 \
  --no-sandbox --disable-gpu

Multiple tabs

Use the target parameter in connect to target a specific tab by URL, title, or target ID. Use the tabs tool to list available targets.

File storage

Baselines and session recordings are stored under the project root:

<project-root>/
  .frontend-debugger/
    baselines/         # Visual regression baselines (homepage/1440.png, ...)
    sessions/          # Persisted session recordings (session-abc123.json)
    verify/            # verify_change combined baselines (component + a11y)
    replays/           # Exported rrweb replay HTML

These directories are created automatically. Add them to .gitignore if you don't want to track baselines in version control, or commit them to share across the team.