Setup Guide

Setup Guide

Option 1: Run locally

1. Clone

git clone https://github.com/Will-Luck/claude-tools-dashboard.git
cd claude-tools-dashboard

2. Install dependencies

pip install flask python-dotenv

That's it. Two packages, no build step.

3. Run

python app.py

Open http://localhost:8095. The dashboard will show dashes until the first SSE tick (30 seconds), then populate with live data.

4. (Optional) Configure

cp .env.example .env
# Edit .env to change port, paths, etc.

See Configuration for all options.

Option 2: Docker (pre-built image)

docker run -d --name claude-tools-dashboard \
  -p 8095:8095 \
  -v ~/.local/share/rtk:/root/.local/share/rtk:ro \
  -v ~/.code-index:/root/.code-index:ro \
  -v ~/.doc-index:/root/.doc-index:ro \
  -v ~/.claude/.credentials.json:/root/.claude/.credentials.json:ro \
  --network host \
  willluck/claude-tools-dashboard

Also available from GHCR:

docker run -d ... ghcr.io/will-luck/claude-tools-dashboard

Volume mounts explained

Mount	What it gives you	Required?
~/.local/share/rtk	RTK savings data and command history	No -- RTK card shows dashes without it
~/.code-index	jCodeMunch index stats	No -- jCodeMunch card shows dashes
~/.doc-index	jDocMunch index stats	No -- jDocMunch card shows dashes
~/.claude/.credentials.json	Claude usage API access	No -- ticker shows dashes for usage stats

Headroom connects via HTTP (HEADROOM_URL), not a volume. Use --network host so the container can reach the proxy on localhost, or set HEADROOM_URL to your host IP.

Mount only what you have. Everything is optional.

Option 3: Docker (build from source)

git clone https://github.com/Will-Luck/claude-tools-dashboard.git
cd claude-tools-dashboard
docker build -t claude-tools-dashboard .
docker run -d -p 8095:8095 --network host claude-tools-dashboard

Add volume mounts as needed (see table above).

Running as a systemd service

If you want the dashboard to start on boot:

mkdir -p ~/.config/systemd/user

cat > ~/.config/systemd/user/claude-tools-dashboard.service << 'EOF'
[Unit]
Description=Claude Tools Savings Dashboard
After=network.target

[Service]
Type=simple
WorkingDirectory=/path/to/claude-tools-dashboard
ExecStart=/path/to/claude-tools-dashboard/.venv/bin/python app.py
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target
EOF

systemctl --user enable claude-tools-dashboard
systemctl --user start claude-tools-dashboard

What to expect

On first load you'll see dashes everywhere. After about 30 seconds the first SSE push arrives and cards populate. The stats ticker takes up to 3 minutes to show Claude usage data (it caches API responses to avoid rate limits).

If a tool isn't installed or its data isn't accessible, that card stays on dashes permanently. That's fine -- the dashboard works with any combination of tools.