CLAUDE.md

Purpose

This repo is Peaky Peek, a local-first AI agent debugger.

The product has three connected surfaces:

• agent_debugger_sdk/: Python SDK for capturing sessions, events, decisions, checkpoints, and adapters
• api/: FastAPI server for query, replay, streaming, auth, and packaged UI serving
• frontend/: React + TypeScript + Vite UI for trace inspection

Primary loop: instrument an agent with the SDK, persist/query it through the API, inspect and replay it in the frontend.

Repo Map

SDK and tracing

• agent_debugger_sdk/core/: tracing primitives, contexts, emitters, recorders, session/event logic
• agent_debugger_sdk/checkpoints/: checkpoint schemas and validation
• agent_debugger_sdk/adapters/: framework integrations
• agent_debugger_sdk/auto_patch/: auto-instrumentation registry and transport bridge
• agent_debugger_sdk/config.py, transport.py, pricing.py: runtime config, delivery, pricing metadata

Server and storage

• api/: app factory, routes, schemas, services, UI/static hooks
• collector/: ingestion and event pipeline integration
• storage/: database engine, migrations, repositories
• auth/: auth and API key support
• redaction/: security/privacy filters
• pyproject-server.toml: package definition for peaky-peek-server

Frontend

• frontend/src/App.tsx: app composition root
• frontend/src/components/: inspection panels and visualizations
• frontend/src/api/client.ts: API boundary
• frontend/src/types/index.ts: frontend contract mirror
• frontend/src/hooks/, frontend/src/stores/: data flow and state
• frontend/src/App.css: main styling surface

Tests and demos

• tests/: main Python test suite
• tests/auto_patch/: auto-instrumentation coverage
• examples/, scripts/: demo flows and seed scripts

Agent Rules

• Prefer targeted reads over broad scans.
• Prefer rg and rg --files.
• Use python3, not python, for module commands in this environment.
• Do not touch unrelated user changes in the worktree.
• Avoid noisy directories unless directly relevant: .venv*, frontend/node_modules, frontend/dist, dist, .pytest_cache, .ruff_cache, __pycache__, traces/.
• traces/ may emit permission noise during naive filesystem scans.
• Playwright MCP: Use mcp__plugin_playwright_playwright__* tools, NOT mcp__playwright__*. The official mcp__playwright__* tools are misconfigured for Chrome instead of Chromium and will fail.

High-Risk Boundaries

Before changing shared shapes, inspect both sides of the boundary.

API ↔ frontend contract

Check together:

• api/schemas.py
• frontend/src/types/index.ts
• frontend/src/api/client.ts

If sessions, events, replay payloads, analysis payloads, or live summaries change, update these together.

SDK ↔ API contract

If event capture or event fields change, inspect:

• agent_debugger_sdk/core/
• agent_debugger_sdk/checkpoints/
• api/schemas.py
• related route/service code in api/

Auto-instrumentation

If changing auto-patching or adapters, inspect:

• agent_debugger_sdk/auto_patch/
• agent_debugger_sdk/adapters/
• tests/auto_patch/

Frontend behavior

If changing a UI panel, inspect:

• frontend/src/App.tsx
• the target component
• any related hooks/store files
• frontend/src/types/index.ts
• frontend/src/api/client.ts when data shape assumptions are involved

Default Workflow

1. Orient

Start with:

git status --short
rg --files agent_debugger_sdk api frontend/src tests

Then read the smallest set of files that defines the target path and its adjacent boundary.

2. Change

Make the narrowest safe edit that solves the problem.

3. Validate

Run the smallest meaningful validation for the area you changed.

Validation Defaults

Python and server changes

ruff check .
python3 -m pytest -q

Use targeted tests when possible, for example:

python3 -m pytest -q tests/test_api_contract.py -k sessions

Full-stack scenario tests live in tests/e2e/ (marker e2e): they start a real uvicorn subprocess with a temp SQLite database and drive the SDK over real HTTP. They run as part of the default suite; opt out with -m 'not e2e'. Run them alone with python3 -m pytest -q tests/e2e.

Frontend changes

cd frontend && npm run build

Dev servers

make server
make frontend

Demo flows

make demo-seed
make demo-live
make demo-safety
make demo-research

When To Use Which Command

• Use git status --short when you need a fast read on the working tree before making changes or committing.
• Use rg --files agent_debugger_sdk api frontend/src tests when you are orienting to the repo or locating the narrowest set of relevant files.
• Use git diff --stat when you want a quick size and scope summary of current edits before deeper review.
• Use ruff check . after Python, API, storage, auth, redaction, or SDK changes.
• Use python3 -m pytest -q after meaningful backend or SDK changes, especially when behavior or contracts changed.
• Use a targeted pytest command such as python3 -m pytest -q tests/test_api_contract.py -k sessions when you changed one area and want fast feedback before running the full suite.
• Do not chase per-file coverage numbers for api/*_routes.py locally: coverage.py under-records FastAPI handler bodies exercised through httpx ASGITransport in some environments (verified with a manual sys.settrace probe — the lines do execute). Trust passing response assertions; CI measures coverage independently.
• Use cd frontend && npm run build after any TypeScript, React, or UI contract change.
• Use make server when you need the FastAPI app running locally for API or integration checks.
• Use make frontend when you need the Vite UI running for manual inspection.
• Use make demo-seed before demo recording or when you need example session data in the system.
• Use make demo-live, make demo-safety, or make demo-research when validating the demo flows or generating showcase traces.

Change Heuristics

• If you change event types or event payload fields, assume backend schema, frontend types, and tests may all need updates.
• If you change an API route, inspect the route module, api/services.py, schema definitions, and frontend callers.
• If you change storage or collector behavior, inspect ingestion flow and any tests covering persistence and replay.
• If you change UI logic, validate with a frontend build even if the change looks type-local.
• If you change packaging or release logic, inspect both pyproject.toml and pyproject-server.toml.

CI and Release Facts

• CI in .github/workflows/ci.yml runs ruff check . and pytest -q on Python 3.10, 3.11, and 3.12.
• Frontend build is not part of the main CI job, but it is part of local validation and the server publish flow.
• Publishing is tag-driven in .github/workflows/publish.yml:
  • sdk-vX.Y.Z publishes peaky-peek
  • server-vX.Y.Z publishes peaky-peek-server
  • vX.Y.Z publishes both
• The publish workflow derives package versions from the tag and rewrites package metadata during CI.

Quick Commands

git status --short
git diff --stat
ruff check .
python3 -m pytest -q
cd frontend && npm run build
make server
make frontend

Pre-Commit Hooks

Install hooks with pre-commit install after setting up the dev environment.