pulse — internals

Two local analytics CLIs that turn your laptop into a quantified-self setup — no cloud, no telemetry, no subscriptions. This site documents how every piece works, so future-you can debug, extend, or rebuild it from scratch.

● claude-stats →

Where your Claude Code spend goes. Cost by model, cache hit-rate, top tools, top skills (per plugin), top projects, context-window pressure.

5 DuckDB tables4 fish subcommandsnightly 02:00 ingest

● battery-stats →

Real Screen-On-Time, drain-rate, battery health, hourly drain heatmap, charging-period bands.

6 DuckDB tables6 fish subcommands5-min poll + nightly aggregate

● Cross-cutting →

systemd timers, the UTC→IST gotcha, file map across the repo and live install paths.

Architecture

Three-layer pipeline. Sources are the authoritative system surfaces. Storage is two DuckDB files in ~/Documents/{claude,battery}-stats/. Consumers read read-only from those DBs.

Sources (read by ingesters)
ccusagenpx ccusage daily / session
JSONL transcripts~/.claude/projects/**/*.jsonl
sysfs/sys/class/power_supply/BAT0/*
UPower history/var/lib/upower/history-*.dat
Wayland sessionloginctl IdleHint + GNOME ScreenSaver D-Bus
powertopsudo -A powertop --csv
▼
Storage (DuckDB)
claude.duckdbdaily_usage · conversations · conversation_tool_usage · conversation_skill_usage · project_usage
battery.duckdbbattery_samples · upower_rate · upower_charge · discharge_sessions · daily_battery · powertop_runs / top_processes
▼
Consumers
HTML dashboardsPlotly + AMOLED, in /tmp
fish CLIdashboard, ingest, raw <SQL>
Schedulerssystemd user timers (Persistent=true)
Why DuckDB
Embedded analytical DB. Columnar storage, SQL-92, zero-config. Lives as a single file you can cp for backup, rm to reset. Aggregations and rollups happen in pure SQL — no Python ORM.
Why dashboards, not terminal tables
Graphs > tables. The CLIs intentionally expose only one display surface: the interactive HTML dashboard. Stacked bars, donuts, hover tooltips, zoom — all the metrics you'd want from a tabular report, but readable at a glance. Terminal tables were dropped because the dashboard is strictly more informative.