claude-session-status 0.2.11

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 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, stamps initial turn time
• Stop → fires after every Claude response, updates last-turn timestamp
• PostToolUse → fires after every tool call mid-turn, keeps TTL accurate during long multi-tool runs
• SessionEnd → marks session closed

Live view

claude-session-status watch

claude-session-status  (Ctrl-C to quit)

SESSION         TITLE                     PROJECT             LAST TURN      CACHE
abc123def456    Fix auth bug              my-app              0m 12s ago     WARM  ████████░░  4m 48s left
xyz789abcd12    Build dashboard           other-proj          4m 51s ago     WARM  ░░░░░░░░░░  0m 09s left
def456ghi789    Refactor pipeline         old-project         6m 03s ago     EXPIRED  (6m 3s ago)
abc999xyz000    Update tests              done-project        -              ENDED

Refreshes every second.

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 and PostToolUse hooks
claude-session-status mark-end         # Called by SessionEnd hook

DB schema

CREATE TABLE session_status (
    session_id   TEXT PRIMARY KEY,
    title        TEXT,
    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)
• PostToolUse hook is async — never delays tool execution
• 3-retry lock backoff on connect
• Session title read from ai-title entries in the Claude Code transcript JSONL