codeflash-admin/codeflash-agent
1
0
Fork 0
mirror of https://github.com/codeflash-ai/codeflash-agent.git synced 2026-05-04 18:25:19 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
codeflash-agent/packages/blackbox
History
Kevin Turcios eaa83207a0
Fix blackbox dev server command and add repo-root instructions (#48) 
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).
2026-04-29 04:18:39 -05:00
..
src/blackbox perf(models): convert prefix/skill/command tuples to frozensets (#47) 2026-04-29 03:22:50 -05:00
tests Add blackbox package: session flight recorder with HTMX dashboard (#39) 2026-04-28 19:58:43 -05:00
pyproject.toml Add blackbox package: session flight recorder with HTMX dashboard (#39) 2026-04-28 19:58:43 -05:00
README.md Fix blackbox dev server command and add repo-root instructions (#48) 2026-04-29 04:18:39 -05:00

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

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/