claude-session-status 0.1.1

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

claude-session-status

Tracks whether Claude Code sessions are warm (actively running) or cold (ended) in a dedicated DuckDB file.

Problem

claude-session-logger writes to sessions.duckdb at session end via a SessionEnd hook. If a TUI (e.g. the session browser) holds a persistent read-only connection to that file, the write blocks and the hook hangs. This package sidesteps the conflict entirely by using its own DB (~/.claude/claude-session-status/status.duckdb) and never holding an open connection between operations.

What warm/cold means

Status	When set	Meaning
warm	SessionStart hook fires	Claude Code is actively running in this project
cold	SessionEnd hook fires	Session ended (Claude Code exited or was interrupted)

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