eaa83207a0
fastapi[standard] extras aren't resolved at workspace level, so `fastapi dev` fails without `--package blackbox`. Add working commands for both repo root (uvicorn) and package directory (fastapi dev).
2.3 KiB
blackbox
A flight data recorder for AI coding agent sessions.
Why "blackbox"?
Aircraft carry black boxes (flight data recorders) that silently capture everything during a flight, then become invaluable when you need to understand what happened. This package does the same for AI coding agent sessions: it watches, records, and lets you replay what the agent did, how it spent tokens, where it got stuck, and whether the session achieved its goal.
Currently supports Claude Code. Codex and Gemini support is planned.
What it does
Dashboard -- a local HTMX web UI for browsing session transcripts in real time.
- Sidebar with all sessions from
~/.claude/projects/, sorted by recency - Live session detection via filesystem watching (green dot indicator)
- Streaming log view with filter presets (all, compact, important, errors)
- Tool call previews, error highlighting, user message formatting
Analytics models -- structured data types for session-level metrics, weekly trends, project breakdowns, and recommendations. These feed into the analysis pipeline (in progress) that will produce session digests and surface patterns across sessions.
Usage
blackbox serve # open dashboard at http://localhost:7100
blackbox serve --port 8080 # custom port
blackbox serve --no-open # don't auto-open browser
Package structure
src/blackbox/
cli.py # CLI entry point (serve command)
models.py # All domain models (attrs frozen classes)
dashboard/
app.py # FastAPI instance + lifespan
routes.py # API endpoints + SSE log streaming
rendering.py # HTML rendering, filtering, formatting
transcript.py # JSONL transcript parser + session scanner
watcher.py # Watchdog-based live session detection + cache
templates/ # Jinja2 templates (Tailwind + HTMX)
Development
From the repo root:
uv sync
uv run --package blackbox uvicorn blackbox.dashboard.app:app --reload # hot reload on :8000
uv run pytest packages/blackbox/tests/ -v
uv run ruff check packages/blackbox/
From packages/blackbox/:
uv run --package blackbox fastapi dev src/blackbox/dashboard/app.py # hot reload on :8000
uv run pytest tests/ -v
uv run ruff check src/ tests/