A local-first desktop overview for tracking Claude Code usage.
Cost, tokens, sessions, and active coding time, all from your own machine.
Why • Screenshots • Features • How It Works • Install • Getting Started • macOS Troubleshooting • Tech Stack
Claude Code provides powerful assistance, but its usage is difficult to observe in aggregate.
Typical questions are hard to answer:
- How much did I actually spend today or this week?
- Which models or sessions consume most of the cost?
- How long am I actively coding with Claude?
- Am I using caching effectively?
- Do I have long, uninterrupted coding sessions without breaks?
Lumo exists to answer these questions locally, using the data Claude Code already emits.
No accounts. No cloud dashboards. No data leaving your machine.
Lumo runs a local daemon and desktop app to collect Claude Code telemetry and present it as dashboards. It stores data in a local SQLite database and renders a native desktop UI (Tauri + Next.js).
The goal is not to analyze your code or conversations, but to provide clear visibility into usage patterns, cost, and time.
Lumo is built for developers who want to understand:
- where Claude Code time and spend go every day
- which sessions/models are driving most usage
- whether work patterns are sustainable (long streaks, break timing, etc.)
On first launch, Lumo also attempts to configure Claude Code locally so telemetry and hook events are forwarded to the Lumo daemon automatically.
Lumo provides a desktop dashboard for understanding Claude Code usage at a glance: cost trends, token breakdown, session counts, code changes, and activity heatmaps.
An at-a-glance overview of your Claude Code usage:
- Total cost, tokens, lines changed, and session count
- Cost trends by model
- Activity heatmap (last year)
- Time range switching (Today / Week / Month)
Browse all Claude Code sessions with full message history:
- Project-based session grouping and filtering
- Session list with project, branch, message count, and updated time
- Session detail view with cost/tokens/duration metadata
- Session highlights (tool calls, tool results, failures, touched files)
- Essential-only mode for dense sessions
- Virtualized message rendering for long transcripts
- Tool call/result blocks, markdown rendering, and raw payload inspection
Inspect tool usage behavior across your Claude Code sessions:
- Top tools by usage volume
- Success rate by tool
- Average duration by tool
- Code edit decisions (accept/reject) with language breakdown
- Tool timeline trends across the selected period
Usage insights derived directly from local telemetry:
- Cache hit rate trends
- Cost efficiency over time
- Peak coding hours
- Error rate and session length distribution
- Token usage by model
A lightweight "wrapped" summary for your Claude Code habits:
- Period switcher (Today / This Week / This Month / All Time)
- Total collaboration hours
- Session count and average session duration
- Go-to model and favorite tool
- Token breakdown and cost snapshot
- Longest streak and peak hour highlights
- Copy / save share card image
Claude Code ── OTLP logs/metrics + hooks ──▶ Lumo Daemon ──▶ SQLite ──▶ Desktop App
(port 4318) (~/.lumo)
-
Lumo Daemon A lightweight background service that receives Claude Code telemetry (
/v1/logs,/v1/metrics) and hook notifications (/notify), then writes them to a local SQLite database. -
Desktop App A native desktop application (built with Tauri) that reads from the same database and renders dashboards and session views.
-
Local Integration Helpers On app startup, Lumo attempts to:
- ensure the daemon is installed/running
- update
~/.claude/settings.jsonfor OTEL export + hooks - poll stored hook notifications and send OS notifications
The telemetry pipeline and database are local-first.
- No sign-in required
- No cloud services
- No third-party analytics
- No data leaves your machine
All data is stored locally at:
~/.lumo
You can inspect or delete it at any time.
- Open the latest release: https://github.com/zhnd/lumo/releases/latest
- Download the package for your platform
- Install and launch
lumo
On macOS, Lumo will install/manage the bundled lumo-daemon under ~/.lumo/bin
and register a launchd agent on first launch.
Use this if you want to develop or modify Lumo locally.
- Node.js >= 24.12
- pnpm >= 10.26
- Rust (stable)
- Platform dependencies for Tauri v2
git clone https://github.com/zhnd/lumo.git
cd lumo
pnpm install
pnpm tauri:devThis starts the daemon, builds the frontend, and launches the desktop app.
When the app starts, it will also try to configure Claude Code OTEL/hook settings in:
~/.claude/settings.jsonYou can review or edit that file at any time.
This is usually caused by macOS Gatekeeper/quarantine checks on unsigned or newly-downloaded apps, not necessarily because the app is actually broken.
Use one of the following methods after confirming you downloaded Lumo from the official GitHub Releases page:
- Try opening
lumoonce (let it fail) - Open
System Settings→Privacy & Security - Find the blocked app message near the bottom
- Click
Open Anyway, then confirm
If the app is in /Applications:
xattr -dr com.apple.quarantine "/Applications/lumo.app"If you run it from Downloads, replace the path accordingly.
Then try launching the app again.
Note: Do not disable Gatekeeper globally. Only remove quarantine for apps you trust.
| Layer | Technology |
|---|---|
| Desktop shell | Tauri v2 (Rust) |
| Telemetry receiver | Axum + OpenTelemetry |
| Claude Code integration | ~/.claude/settings.json (OTEL + hooks) |
| Database | SQLite (SQLx) |
| Frontend | Next.js 16, React 19 |
| State & data | TanStack Query |
| Styling | Tailwind CSS v4 + shadcn/ui |
| Charts | ECharts + Recharts |
| Type sharing | Typeshare (Rust → TypeScript) |
lumo/
├── crates/daemon/ # OTLP receiver service
├── crates/shared/ # Database entities, repositories, migrations
├── src-tauri/ # Tauri backend (IPC commands)
└── packages/ui/ # Desktop UI
├── app/ # Next.js routes
├── modules/ # Overview, Sessions, Tools, Performance, Wrapped
└── components/ # Shared UI components
MIT