Skip to content

session-tracker.md

Latest commit

 

History

History
100 lines (70 loc) · 2 KB

session-tracker.md

File metadata and controls

100 lines (70 loc) · 2 KB

Session Tracker

A provider-agnostic AI session tracker for terminal-based workflows. Works with Claude, Codex, Ollama, or any other command you want to wrap.

Files

  • desktop_checklist.py: desktop UI
  • register_ai_session.py: lifecycle CLI
  • checklist_store.py: shared store and session model

Storage

The tracker persists to:

~/.session_tracker.json

The desktop app polls this store, so externally tracked sessions show up in the UI without manual re-entry.

Launch The Desktop App

python3 desktop_checklist.py

UI-First Workflow

You do not need to run terminal commands manually for normal use.

From the sidebar you can launch:

  • Launch Codex
  • Launch Claude
  • Launch Ollama
  • Launch Custom

Each starts a tracked session through the UI and it appears in the sessions panel automatically.

Manual Session Commands

Open a session:

python3 register_ai_session.py open \
  --title "Auth fixes" \
  --provider Claude \
  --model Sonnet \
  --terminal claude \
  --command claude \
  --cwd "$PWD"

Heartbeat an active session:

python3 register_ai_session.py heartbeat --session-id <session-id>

Close a session:

python3 register_ai_session.py close --session-id <session-id> --exit-code 0

List sessions:

python3 register_ai_session.py list

Wrapped Session Tracking

Use wrap when you want the tracker to manage the lifecycle automatically. The desktop UI launch buttons use this flow behind the scenes.

python3 register_ai_session.py wrap \
  --title "Claude work" \
  --provider Claude \
  --model Sonnet \
  --terminal claude \
  -- claude

Session Model

Tracked session fields:

  • explicit open time
  • last heartbeat time
  • explicit close time
  • effective status (active, stale, closed)
  • provider and model
  • terminal and command
  • working directory
  • host name
  • process id when available
  • notes and exit code

The tracker marks an open session as stale if it has not heartbeated within 5 minutes.