Quick Start

From zero to flight recorder in four steps. The entire setup takes about 30 seconds.

Initialize Dashcam

Run the init command to install Claude Code hooks and set up the local data directory:

Terminal

npx dashcam init

You will see output confirming each step:

Dashcam v1.0.0

  Installing Claude Code hooks... done
  Creating ~/.dashcam/ directory... done
  Initializing SQLite database... done
  Running health check... all systems go

Ready. Run `dashcam start` to launch the daemon.

Start the Daemon

Launch the Dashcam daemon and web dashboard:

Terminal

npx dashcam start

Dashcam daemon started on http://localhost:57580
  WebSocket server ready
  JSONL file watcher active
  Screenshot service standby
  Waiting for Claude Code events...

Open the Dashboard

Navigate to the Dashcam dashboard in your browser:

http://localhost:57580

You will see the session browser — an empty grid waiting for its first session. The status bar at the bottom shows the daemon is running and listening for events.

Run Claude Code

Open a new terminal and start a Claude Code session as you normally would:

Terminal

claude

The moment Claude Code starts, Dashcam captures the SessionStart hook event. Switch back to the dashboard — you will see a live session card appear in the browser with a pulsing green indicator. Events stream onto the timeline in real-time as the agent works.

What Just Happened?

Behind the scenes, dashcam init performed three things:

Installed Claude Code hooks. Dashcam added entries to your ~/.claude/settings.json file under the hooks section. These hooks fire lightweight HTTP POST requests to the Dashcam daemon on every SessionStart, PreToolUse, PostToolUse, Stop, and SubagentStart/Stop event. Each request uses --max-time 1 and || true so it never blocks Claude Code — even if Dashcam is not running.
Created the data directory. A ~/.dashcam/ directory was created containing:
- dashcam.db — SQLite database (WAL mode enabled) storing events, sessions, captures, and decisions
- captures/ — directory for screenshots and video recordings
- config.json — configuration file with sensible defaults
Started the daemon. The dashcam start command launched a Bun-powered daemon that:
- Serves the web dashboard on port 57580
- Opens a WebSocket server for real-time streaming to the browser
- Watches ~/.claude/projects/ for JSONL session files
- Listens for HTTP hook events from Claude Code
- Manages the screenshot capture pipeline (activated when a dev server is detected)

Want to verify everything is healthy? Run npx dashcam doctor to check that hooks are installed, the database is accessible, and Playwright is available for screenshots.

What Happens Next

As Claude Code works, Dashcam captures every event and organizes it into a session. When the agent writes or edits files, Dashcam checks for a running dev server and captures screenshots automatically. When the session ends, the session card in the browser updates with a thumbnail, duration, and event count.

Click any session card to enter the timeline view — a canvas-rendered, scrubable timeline where you can drag the playhead and watch every panel update to show exactly what was happening at that moment.

Customizing Your Setup

Installation — Alternative install methods, remote servers, Docker
Configuration — Tweak capture intervals, ports, retention, and window management

Quick Start

On this page