claude-session-status 0.1.0

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

claude-session-status

Tracks warm/cold status of Claude Code sessions in a dedicated DuckDB file — separate from claude-session-logger to avoid file-lock conflicts.

Why

claude-session-logger writes to sessions.duckdb at session end. If a TUI holds a persistent read-only connection to that file, the write blocks. This package uses its own DB (~/.claude/claude-session-status/status.duckdb) and never holds an open connection between operations.

Install

pip install claude-session-status

Hook integration

Add to ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      {"type": "command", "command": "claude-session-status mark-warm"}
    ],
    "SessionEnd": [
      {"type": "command", "command": "claude-session-status mark-cold"}
    ]
  }
}

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

Commands

# Live-refresh table of warm/cold sessions (Ctrl-C to quit)
claude-session-status watch

# Called by hooks (reads JSON from stdin)
claude-session-status mark-warm
claude-session-status mark-cold

DB schema

CREATE TABLE session_status (
    session_id TEXT PRIMARY KEY,
    project    TEXT,
    cwd        TEXT,
    started_at TIMESTAMP,
    updated_at TIMESTAMP,
    status     TEXT  -- 'warm' | 'cold'
)

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

Design

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