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

Run once after install:

```bash
claude-session-status install-hooks
```

This writes the required hooks into `~/.claude/settings.json` automatically, preserving any existing config. To remove them:

```bash
claude-session-status uninstall-hooks
```

**What each hook does:**
- `SessionStart` → records session opened, stamps initial turn time
- `Stop` → fires after every Claude response, updates last-turn timestamp
- `PostToolUse` → fires after every tool call mid-turn, keeps TTL accurate during long multi-tool runs
- `SessionEnd` → marks session closed

## Live view

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

```
claude-session-status  (Ctrl-C to quit)

SESSION         TITLE                     PROJECT             LAST TURN      CACHE
abc123def456    Fix auth bug              my-app              0m 12s ago     WARM  ████████░░  4m 48s left
xyz789abcd12    Build dashboard           other-proj          4m 51s ago     WARM  ░░░░░░░░░░  0m 09s left
def456ghi789    Refactor pipeline         old-project         6m 03s ago     EXPIRED  (6m 3s ago)
abc999xyz000    Update tests              done-project        -              ENDED
```

Refreshes every second.

## Commands

```bash
claude-session-status install-hooks    # Add hooks to ~/.claude/settings.json
claude-session-status uninstall-hooks  # Remove hooks from ~/.claude/settings.json
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 and PostToolUse hooks
claude-session-status mark-end         # Called by SessionEnd hook
```

## DB schema

```sql
CREATE TABLE session_status (
    session_id   TEXT PRIMARY KEY,
    title        TEXT,
    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)
- `PostToolUse` hook is async — never delays tool execution
- 3-retry lock backoff on connect
- Session title read from `ai-title` entries in the Claude Code transcript JSONL
