@tekmidian/pai 0.9.16 → 0.10.0

package/README.md

@@ -1,4 +1,4 @@
-# PAI Knowledge OS — v0.9.10
+# PAI Knowledge OS — v0.10.0
 
 Claude Code has a memory problem. Every new session starts cold — no idea what you built yesterday, what decisions you made, or where you left off. PAI fixes this.
 
@@ -295,6 +295,118 @@ All hooks are TypeScript compiled to `.mjs` modules. They run as separate proces
 
 ---
 
+## Session Management
+
+PAI gives you a complete picture of every Claude Code session running on your machine — live tabs in iTerm2, paused snapshots on disk, and everything in between.
+
+### The Core Idea: Think in Topics
+
+The user's mental model is simple: "I did something on a given subject. Where was I working on it? Let me continue."
+
+PAI v0.10.0 is built around this. You think in **topics**, not project names or session UUIDs. PAI handles the lookup.
+
+```bash
+pai mdf             # Find every session where you worked on MDF
+pai solar panels    # Free-text search across your prompt history
+pai 0856d40b        # Resume by UUID prefix (from pai sessions)
+pai                 # Show all recent sessions (interactive picker)
+```
+
+When you type `pai mdf`, PAI checks:
+1. Is "mdf" a named session in the catalog? → launch immediately, no picker
+2. Is "mdf" a UUID prefix? → direct filesystem resume
+3. Otherwise → grep `~/.claude/history.jsonl` for matching prompts, show candidate list, you pick a number
+
+The picked session resolves to the best resumable snapshot in the same project directory. PAI probes `claude --resume` automatically. If the snapshot is stale, it starts a fresh Claude in the same directory.
+
+### Daily Verbs
+
+The commands you'll use every day:
+
+```bash
+pai                   # Recent sessions picker (live + disk)
+pai <topic>           # Find + launch session by topic/keyword/UUID
+pai cd <name>         # cd to a project directory (no Claude launch)
+pai pause             # Save state checkpoint (write ## Continue to TODO.md)
+pai pause all         # Pause every live Claude session at once
+pai end               # Finalize: save state + mark session note Completed
+```
+
+And inside Claude Code, the two slash commands that matter:
+
+```
+/pause    →  write checkpoint to TODO.md, print handoff block, then type /exit
+/end      →  same as /pause, plus marks the session note Completed
+```
+
+### Finding Sessions
+
+`pai` (no args) shows two sections:
+
+**Live Sessions** — pulled from AIBroker in real time. One row per active iTerm2 pane running Claude Code. Columns: `#`, `id`, `name`, `at prompt`.
+
+**Recent Sessions** — disk scan of `~/.claude/projects/`, sorted by last-modified.
+
+`pai <topic>` searches your prompt history in `~/.claude/history.jsonl`, groups results by session, and shows a table:
+
+```
+Sessions matching "mdf":
+
+  #  id        when              project                              last matching prompt
+  -  --------  ----------------  -----------------------------------  -------------------------
+  1  6269cf64  2026-05-21 08:20  /…MDF/Infrastruktur/20 - Webseiten  "ok so we recently had an order…"
+  2  abe2d977  2026-02-23 08:40  /…MDF/Infrastruktur/20 - Webseiten  "yes the session notes for Whazaa…"
+
+  Enter # to launch (1-2), or press Enter to cancel:
+```
+
+Type the number and press Enter. PAI launches Claude, resumes if possible, starts fresh if not.
+
+Use `pai <topic> --auto` (or `-y`) to auto-pick #1 without the prompt. Use `pai <topic> 2` to pick #2 directly.
+
+### Power User Access
+
+The full session management namespace is still available for power users:
+
+```bash
+pai sessions              # Live + disk listing (same as bare pai, with more columns)
+pai sessions --all        # Include unnamed orphan sessions
+pai sessions --all-tabs   # Include shell tabs in the live section
+pai sessions goto <name>  # Named-session resolver (same as pai <name>)
+pai sessions list         # Explicit listing (same as pai sessions)
+```
+
+### Pausing All Sessions at Once
+
+When you're done for the day and have multiple Claude windows open:
+
+```bash
+pai pause all             # send "pause session" to every live Claude pane
+pai pause all --dry-run   # preview what would be sent
+pai pause all --exit      # also send /exit after each session saves state
+```
+
+AIBroker must be running for this to work. Shell tabs (bare zsh, SSH panes) are automatically skipped — only Claude Code panes receive the pause command. The count of skipped tabs is printed to stderr.
+
+### /pause and /end Inside Claude Code
+
+Type `/pause` or `/end` from inside an active Claude Code session (not from a shell — these are Claude Code slash commands, not CLI commands):
+
+- `/pause` — Claude writes a `## Continue` block to the project's `TODO.md`, prints a handoff summary with the session ID, then tells you to type `/exit`. The next session starts by reading that TODO.md block and picking up exactly where you left off.
+- `/end` — Same as `/pause`, plus Claude marks the session note as Completed and writes a final summary. Use this when you're genuinely done with a topic, not just pausing mid-task.
+
+After either command, type `/exit` to exit Claude Code cleanly.
+
+### Why /exit and Not Ctrl+C
+
+Ctrl+C or closing the terminal kills the Claude Code process abruptly. The session note generation hook never fires, the checkpoint is not written, and the session cannot be resumed with `claude --resume`.
+
+`/exit` sends a clean shutdown signal. Claude Code runs its Stop and Session End hooks, which trigger PAI to write the session note, push the final summary to the daemon, and save a resumable snapshot. The difference in recovery quality between a clean `/exit` and a Ctrl+C is significant for long sessions.
+
+If you do accidentally close a terminal, use `pai sessions --all` to find the orphaned transcript. The `/reconstruct` skill can retroactively generate a session note from it.
+
+---
+
 ## Automatic Session Notes
 
 PAI automatically writes structured session notes after every session ends — no manual journaling required. The daemon spawns a headless Claude CLI process (using your Max plan, not the API) to summarize the JSONL conversation transcript combined with recent git history.
@@ -801,7 +913,7 @@ External URLs (`https://`, `mailto:`, etc.) are excluded — only relative paths
 
 ## Release History
 
-21 releases shipped from v0.7.2 to v0.9.10 (March 19 – April 13, 2026):
+31 releases shipped from v0.7.2 to v0.10.0 (March 19 – May 21, 2026):
 
 | Version | Feature |
 |---------|---------|
@@ -829,6 +941,15 @@ External URLs (`https://`, `mailto:`, etc.) are excluded — only relative paths
 | v0.9.8 | Privacy tags, compact search format, npx install |
 | v0.9.9 | Fix advisor mode to delegate to haiku instead of hoarding in opus |
 | v0.9.10 | Cognee-inspired three-tier memory: entity deduplication, graph-completion search, feedback EMA |
+| v0.9.11 | Session-commands hook for truncation resilience |
+| v0.9.12 | Dispatcher uses openFederation directly for kg_search/feedback |
+| v0.9.13 | Emit chunk IDs in memory_search output |
+| v0.9.14 | AIBroker live-session integration: `pai sessions` shows live iTerm2 panes |
+| v0.9.15 | `pai pause all`: pause every live Claude session at once via AIBroker |
+| v0.9.16 | createHash import fix, registry scan clc fallback map |
+| v0.9.17 | Switch live-session listing to `sessions` IPC (metadata-only, faster); `--all-tabs` flag |
+| v0.9.18 | `pai projects`: moved-project auto-detect, rebind command, active-only default listing |
+| v0.10.0 | Topic-first redesign: `pai <topic>` universal resolver, history search, sticky tab titles |
 
 ---