Metadata-Version: 2.4
Name: pk-session-manager
Version: 0.1.0
Summary: Parse, index, name, and compress AI agent sessions from Claude Code, Codex, Gemini, and beyond.
Project-URL: Homepage, https://github.com/kingkillery/pk-session-manager
Project-URL: Repository, https://github.com/kingkillery/pk-session-manager
Project-URL: Issues, https://github.com/kingkillery/pk-session-manager/issues
Author: kingkillery
License: MIT
License-File: LICENSE
Keywords: agents,claude,cli,codex,gemini,llm,session,transcripts,tui
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Environment :: Console :: Curses
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Requires-Dist: httpx>=0.27
Requires-Dist: platformdirs>=4.2
Requires-Dist: pydantic>=2.6
Requires-Dist: python-dateutil>=2.9
Requires-Dist: rich>=13.7
Requires-Dist: textual>=0.60
Requires-Dist: tomli>=2.0; python_version < '3.11'
Provides-Extra: compress
Requires-Dist: llmlingua>=0.2.2; extra == 'compress'
Requires-Dist: torch>=2.2; extra == 'compress'
Requires-Dist: transformers>=4.40; extra == 'compress'
Provides-Extra: desktop
Requires-Dist: pywebview>=5.0; extra == 'desktop'
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# pk-session-manager

[![PyPI](https://img.shields.io/pypi/v/pk-session-manager.svg)](https://pypi.org/project/pk-session-manager/)
[![Python](https://img.shields.io/pypi/pyversions/pk-session-manager.svg)](https://pypi.org/project/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

```bash
pip install pk-session-manager
```

Optional extras:

```bash
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)

```powershell
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

```powershell
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.
