Docs / Install

Install Claude Usage Dashboard

This Pages site is the documentation shell for a local-first dashboard. Use it to choose an install path, understand the runtime requirements, and jump into the workflow docs once the app is running.

Why this site is static

GitHub Pages publishes a static companion site for this project: guides, screenshots, and automation artifacts. The live dashboard itself still requires a server runtime with Next.js routes, tRPC, SSE, and SQLite.

Download desktop build Open workflow guides Browse screenshots

Start here

Recommended install path

If you want the cleanest first-run experience, start with the packaged desktop release. Docker and source are still documented here when you want a containerized or fully hackable setup.

Fastest setup

Recommended: desktop release

The fastest path if you want the real dashboard without setting up Node or Docker first.

Download the archive for Windows, macOS, or Linux.
Extract the bundle and launch the packaged app.
Point it at your local Claude data and start exploring sessions.

Open releases

Container

Run with Docker

Use a local container when you want repeatable setup and a clean runtime boundary.

docker compose up -d

docker run -d -p 3000:3000 \
  -v ~/.claude:/home/nextjs/.claude:ro \
  -v ./data:/app/data \
  ghcr.io/jerrettdavis/claudeusagedashboard:latest

Source

Run from source

Best for contributors and anyone extending the dashboard, guides, or automation workflows.

git clone https://github.com/JerrettDavis/ClaudeUsageDashboard.git
cd ClaudeUsageDashboard
npm install
npm run dev

Dashboard overview showing metrics, quick actions, and recent sessions. — **The first screen you should expect** The dashboard opens with high-signal metrics, sync actions, and recent session activity so users see value immediately. Click image to expand

What happens next

Once the app is running, open the dashboard, confirm recent activity is visible, and use the built-in guides to learn the sessions and monitoring views.

Before you install

System requirements

Desktop build

No Node.js setup required. Download the packaged app for your platform and run it locally.

Windows, macOS, and Linux archives are published on GitHub Releases.
The bundle includes the runtime, so setup is minimal.

Docker

Use Docker when you want a reproducible local deployment that mounts your Claude data.

Docker Engine or Docker Desktop installed locally.
A writable local data directory for SQLite.
A readable Claude session directory mounted into the container.

Source

Running from source is ideal when you want to customize UI, routes, or workflows.

Node.js installed locally.
The repository cloned to your machine.
Access to your local Claude session files under ~/.claude.

Detailed setup

Alternative install methods

Use Docker when you want a clean runtime boundary, or run from source when you are extending the codebase. Both routes are fully local and keep your data on your own machine.

Docker Compose

Start the app in the background and then open the dashboard in your browser.

docker compose up -d

Source workflow

Install dependencies and start the Next.js server in development mode.

npm install
npm run dev

Need the full command reference?

The README documents all supported paths in more detail, including the exact Docker mount configuration and source commands.

Read installation docs Open quick start

Sanity check

Verify the install

Open the dashboard. The main dashboard should show usage metrics, quick actions, and recent activity.
Run a sync if needed. Use the sync action so the local database picks up your latest Claude sessions.
Open the Sessions view. Confirm that project names, timestamps, tokens, and costs appear in the session list.
Open the guides hub. Use the built-in guides page to orient yourself before diving into monitoring or session detail views.

Open the guides hub next

Use the workflow docs once you have the app running so the main surfaces feel obvious instead of exploratory.

Open workflow guides

See what the dashboard looks like

Compare your local app to the committed screenshot reference if you want a quick visual sanity check.

Browse screenshots