codeflash-agent/packages/blackbox/README.md

# 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

```bash
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:

```bash
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/`:

```bash
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/
```