Real-time browser dashboard for Claude Code session states.
Claude Code hooks ──POST JSON──▶ HTTP server ──SSE──▶ Browser dashboard
Claude Code fires hooks on session lifecycle events. The dashboard installs hooks that curl/Invoke-WebRequest each event to a local HTTP server. The server maintains an in-memory session store and pushes updates to all connected browsers via Server-Sent Events (SSE).
npx @kosinal/claude-code-dashboardOpen http://localhost:8377 in your browser, then start a Claude Code session — it will appear on the dashboard automatically.
Press Ctrl+C to stop. Hooks are removed automatically on exit.
npx @kosinal/claude-code-dashboard # start on default port 8377
npx @kosinal/claude-code-dashboard --port 9000 # use a custom portStarts the server and installs temporary hooks into ~/.claude/settings.json. Hooks are cleaned up when the dashboard stops.
npx @kosinal/claude-code-dashboard install # persistent install
npx @kosinal/claude-code-dashboard install --port 9000 # custom portCopies the server to ~/.claude/dashboard/ and installs persistent hooks. When any Claude Code session starts, the dashboard auto-launches in the background and opens in your browser.
Install mode also creates:
- A desktop/Start Menu shortcut to open the dashboard
- A
claude-dashboard://protocol handler for quick access
npx @kosinal/claude-code-dashboard uninstallRemoves hooks from settings.json, deletes ~/.claude/dashboard/, and cleans up shortcuts and protocol handlers.
npx @kosinal/claude-code-dashboard stop # gracefully stop a running server
npx @kosinal/claude-code-dashboard restart # restart, or start fresh if not running| Flag | Description |
|---|---|
--port <number> |
Port to listen on (default: 8377) |
--no-hooks |
Start the server without installing hooks |
--no-open |
Don't auto-open browser on start |
-h, --help |
Show help message |
- Real-time session cards — each Claude Code session appears as a card with status, project folder, working directory, last event, and time-ago timestamp
- Status indicators — animated dots show running (yellow, pulsing), waiting for input (blue, breathing), or done (green, static)
- Browser notifications — opt-in desktop notifications when a session transitions to "waiting for input" (toggle in the header)
- Event logging — toggle detailed event logging to
~/.claude-code-dashboard/logs/from the dashboard footer - Server controls — restart or stop the server directly from the dashboard UI
- Connection indicator — visual feedback showing whether the browser is connected to the server
- Idle cleanup — sessions are automatically removed after 5 minutes of inactivity
The dashboard tracks session status based on multiple hook events:
| Hook event | Dashboard status | Description |
|---|---|---|
SessionStart |
Done | New session, no prompt yet |
UserPromptSubmit |
Running | User submitted a prompt |
PreToolUse |
Waiting / Running | Waiting if tool needs approval; running if auto-approved |
PermissionRequest |
Waiting | Tool requires explicit user permission |
PostToolUse |
Running | Tool finished, Claude is working |
Stop |
Done | Session stopped |
SessionEnd |
(removed) | Session removed from dashboard |
The PreToolUse logic is context-aware: interactive tools (Write, Edit, NotebookEdit, ExitPlanMode, AskUserQuestion) set status to "waiting", unless the session is in acceptEdits mode where edit tools are auto-approved.
Sessions are sorted by status (running first, then waiting, then done) and by last update time within each group.
- Sessions that were already running before the dashboard started are not tracked. Only sessions that fire a hook event after the dashboard is running will appear.
- Session state is held in memory — restarting the dashboard clears all sessions.
- Node.js >= 18
npm install # install dev dependencies
npm run build # bundle with tsup (ESM, node18 target)
npm test # run tests (node:test with --experimental-strip-types)
npm run lint # check for lint issues
npm run lint:fix # auto-fix lint issuesGNU GENERAL PUBLIC LICENSE