claude-session-status 0.1.2

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

When you run Claude Code across multiple projects and terminals, there's no built-in way to see which sessions are still active. You end up switching between terminals, checking for running processes, or losing track of what's open. This package gives you a live view — one command shows every session and whether it's currently running or has ended.

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