observability:session

Session

Query Claude Code history from a DuckDB index over the JSONL session files. Report each figure with the named query or SQL that produced it, and any index-health alert or Known Blind Spot that bounds it.

Current session ID: ${CLAUDE_SESSION_ID}

Arguments

• --refresh: run refresh.ts --refresh before querying. Default: the incremental refresh.
• --host <label>: scope queries through the host param. Default: every host, including local.
• --since <date>: pass as the after_date param. Default: the full index.

Database

The index is ~/.local/share/claude-sessions/session.duckdb (under $XDG_DATA_HOME when set). Use that path directly in every query and agent prompt.

Refresh

Run refresh.ts before querying. It imports changed files, drops rows for deleted ones, and prints the DB path. Within --max-age (default 300 seconds) of the last refresh it exits without opening the database. Pass --refresh when the user asks for the latest data.

bun ${CLAUDE_SKILL_DIR}/scripts/refresh.ts

Querying

Open the index with duckdb -readonly -json -init ${CLAUDE_SKILL_DIR}/resources/limits.sql:

• -readonly: a read-write open blocks refreshes and other readers.
• -init limits.sql: caps memory and threads. DuckDB's per-process defaults let a few concurrent readers freeze the machine.
• -json: the default box format truncates to 40 rows, and -csv breaks rows on newlines embedded in command and text.

Parameterize with SET VARIABLE and read with getvariable('key'). Quote reserved words: SET VARIABLE "limit" = 5.

duckdb -readonly -json -init ${CLAUDE_SKILL_DIR}/resources/limits.sql ~/.local/share/claude-sessions/session.duckdb "SELECT model, SUM(output_tokens) FROM message_usage GROUP BY model"
duckdb -readonly -json -init ${CLAUDE_SKILL_DIR}/resources/limits.sql ~/.local/share/claude-sessions/session.duckdb < ${CLAUDE_SKILL_DIR}/resources/queries/stats.sql

scripts/usage.ts renders one session's token-burn timeline (--session <id>), or the top sessions by estimated cost (--days <n>). Its cost estimate comes from public API rates and comes to about 0.97 of billed spend.