claude-session-status 0.2.5

Track warm/cold status of Claude Code sessions in a dedicated DuckDB file

claude-session-status

Know at a glance whether your Claude Code prompt cache is still warm — before you send your next message.

Problem

Claude's prompt cache has a 5-minute TTL. If you haven't sent a message in over 5 minutes, the cache expires and Claude re-processes your full conversation context on the next turn — costing more tokens. When you're juggling multiple projects across several terminals, it's easy to lose track of which sessions are still within that window.

This package tracks the timestamp of your last Claude turn per session and shows you a live countdown so you know exactly how much time you have left before the cache expires.

What the statuses mean

Status	Meaning
WARM + countdown	Last turn was less than 5 min ago — cache is active, next message is cheap
EXPIRED	Last turn was more than 5 min ago — cache is gone, next message re-processes full context
ENDED	Session was closed

Install

pip install claude-session-status

Hook integration

Run once after install:

claude-session-status install-hooks

This writes the three required hooks into ~/.claude/settings.json automatically, preserving any existing config. To remove them:

claude-session-status uninstall-hooks

What each hook does:

• SessionStart → records session opened
• Stop → fires after every Claude response, stamps the last-turn timestamp
• SessionEnd → marks session closed

Claude Code pipes session JSON to stdin; the scripts extract session_id, project, and cwd automatically.

Live view

claude-session-status watch

claude-session-status  (refreshes every 5s, Ctrl-C to quit)

SESSION         PROJECT                 LAST TURN      CACHE
abc123def456    my-project              2m 14s ago     WARM  ████████░░  2m 46s left
xyz789abcd12    other-proj              4m 51s ago     WARM  ░░░░░░░░░░  0m 09s left
def456ghi789    old-project             6m 03s ago     EXPIRED  (6m 3s ago)
abc999xyz000    done-project            -              ENDED

Status line integration

The Stop hook also touches /tmp/claude-cache-warmth-<session_id> after each turn. If your Claude Code status line reads that file's mtime (via statusline-command.sh), it will show a live bar and countdown for the current session:

~  (main)  Sonnet  ctx:42%  ████████░░ 2m46s

The bar empties and turns to ░░░░░░░░░░ expired once the 5-minute TTL passes.

Commands

claude-session-status install-hooks    # Add hooks to ~/.claude/settings.json
claude-session-status uninstall-hooks  # Remove hooks from ~/.claude/settings.json
claude-session-status watch            # Live cache status table (Ctrl-C to quit)
claude-session-status mark-start       # Called by SessionStart hook
claude-session-status mark-turn        # Called by Stop hook
claude-session-status mark-end         # Called by SessionEnd hook

DB schema

CREATE TABLE session_status (
    session_id   TEXT PRIMARY KEY,
    project      TEXT,
    cwd          TEXT,
    started_at   TIMESTAMP,
    last_turn_at TIMESTAMP,
    status       TEXT  -- 'active' | 'ended'
)

DB location: ~/.claude/claude-session-status/status.duckdb

Design

• Runtime dependency: duckdb only
• Every DB access: open → read/write → close. No persistent connections.
• Hook commands are silent on success, errors go to stderr (never block Claude Code)
• 3-retry lock backoff on connect