Metadata-Version: 2.4
Name: claude-session-status
Version: 0.1.2
Summary: Track warm/cold status of Claude Code sessions in a dedicated DuckDB file
Project-URL: Homepage, https://github.com/keith-fajardo/claude-session-status
Project-URL: Repository, https://github.com/keith-fajardo/claude-session-status
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: duckdb>=0.9

# 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

```bash
pip install claude-session-status
```

## Hook integration

Add to `~/.claude/settings.json`:

```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

```bash
# 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

```sql
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
