pk-session-manager

Parse, index, name, and compress AI agent sessions from Claude Code, Codex, Gemini, and pluggable adapters.

Provides:

• A unified Python API and SQLite index over heterogeneous session sources
• A sm CLI for listing, viewing, renaming, describing, and compressing sessions
• A Textual TUI for browsing sessions across all agents
• Optional LLMLingua-2 token-aware compression for feeding a past session back into a model
• Optional OpenRouter-powered auto-naming via openai/gpt-oss-120b
• An optional PyWebView desktop shell

Install

pip install pk-session-manager

Optional extras:

pip install 'pk-session-manager[compress]'   # LLMLingua-2 semantic compression
pip install 'pk-session-manager[desktop]'    # PyWebView desktop shell
pip install 'pk-session-manager[dev]'        # pytest + ruff

Dev install (editable)

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .

For semantic compression: pip install -e ".[compress]". For the desktop shell: pip install -e ".[desktop]".

Quick start

sm index            # discover and index sessions from all known sources
sm list             # show indexed sessions
sm show <id|name>   # render a session's turns
sm compress <id>    # write a token-compressed bundle to stdout
sm-tui              # launch the Textual TUI

Storage

State lives under ~/.session-manager/:

• sessions.db — SQLite + FTS5 index (sessions, turns, tool calls, names)
• config.toml — user config (sources, compression target, OpenRouter key location)
• models/ — LLMLingua-2 model cache (downloaded lazily on first compression)

Sources

Out of the box:

• Claude Code — ~/.claude/projects/<encoded-cwd>/<uuid>.jsonl
• Codex — ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl and ~/.codex/archived_sessions/
• Gemini — ~/.gemini/tmp/<project>/chats/session-*.jsonl
• Generic JSONL — point a YAML at any path and provide a field mapping

Auto-naming

If OPENROUTER_API_KEY is set, sm describe <id> will call openai/gpt-oss-120b via OpenRouter and store a short title + 1-sentence description. Heuristic names (first user prompt + cwd) are generated for free at index time.