Metadata-Version: 2.4
Name: claude-session-status
Version: 0.2.0
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

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

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

## Hook integration

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

```json
{
  "hooks": {
    "SessionStart": [
      {"type": "command", "command": "claude-session-status mark-start"}
    ],
    "Stop": [
      {"type": "command", "command": "claude-session-status mark-turn"}
    ],
    "SessionEnd": [
      {"type": "command", "command": "claude-session-status mark-end"}
    ]
  }
}
```

- `SessionStart` → records session opened
- `Stop` → fires after every Claude response, updates the last-turn timestamp
- `SessionEnd` → marks session closed

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

## Live view

```bash
claude-session-status watch
```

```
claude-session-status  (refreshes every 5s, Ctrl-C to quit)

SESSION         PROJECT                 LAST TURN      CACHE
abc123def456    my-project              2m 14s ago     WARM  ████████░░  2m 46s left
xyz789abcd12    other-proj              4m 51s ago     WARM  ░░░░░░░░░░  0m 09s left
def456ghi789    old-project             6m 03s ago     EXPIRED  (6m 3s ago)
abc999xyz000    done-project            -              ENDED
```

## Commands

```bash
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 hook
claude-session-status mark-end    # Called by SessionEnd hook
```

## DB schema

```sql
CREATE TABLE session_status (
    session_id   TEXT PRIMARY KEY,
    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)
- 3-retry lock backoff on connect
