Metadata-Version: 2.4
Name: agent-sessions
Version: 0.2.0
Summary: Discover and inspect local AI coding agent sessions
Project-URL: Homepage, https://github.com/larsderidder/agent-sessions
Project-URL: Repository, https://github.com/larsderidder/agent-sessions
Project-URL: Issues, https://github.com/larsderidder/agent-sessions/issues
Author-email: Lars de Ridder <lars@xithing.io>
License-Expression: MIT
License-File: LICENSE
Keywords: agent,ai,claude,codex,discovery,sessions
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# agent-sessions

[![PyPI](https://img.shields.io/pypi/v/agent-sessions)](https://pypi.org/project/agent-sessions/)
[![Tests](https://github.com/larsderidder/agent-sessions/actions/workflows/test.yml/badge.svg)](https://github.com/larsderidder/agent-sessions/actions/workflows/test.yml)
[![Python 3.11+](https://img.shields.io/pypi/pyversions/agent-sessions)](https://pypi.org/project/agent-sessions/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

Discover and inspect local AI coding agent sessions (Claude Code, Codex, OpenCode, Pi).

> **Looking for a ready-made supervision tool?** Check out [Tether](https://github.com/larsderidder/tether).

## Install

```bash
pip install agent-sessions
```

## Usage

```python
from agent_sessions import discover_sessions, get_session_detail, RunnerType

# Find all recent sessions
sessions = discover_sessions()
for s in sessions:
    print(f"{s.runner_type.value}: {s.directory} ({s.message_count} messages)")

# Filter by agent type
claude_sessions = discover_sessions(runner_type=RunnerType.CLAUDE_CODE)

# Filter by project directory
project_sessions = discover_sessions(directory="/home/user/my-project")

# Load full message history
detail = get_session_detail(sessions[0].id, sessions[0].runner_type)
for msg in detail.messages:
    print(f"[{msg.role}] {msg.content[:80]}")
```

## Supported agents

| Agent | Session location | Format |
|-------|-----------------|--------|
| Claude Code | `~/.claude/projects/` | JSONL per session |
| Codex | `~/.codex/sessions/` | JSONL rollout files |
| OpenCode | `~/.local/share/opencode/opencode.db` | SQLite database |
| Pi | `~/.pi/agent/sessions/` | JSONL per session |

Each provider also detects whether sessions are currently running by inspecting the process table.

## Configuration

All providers support environment variables to override default paths:

| Variable | Provider | Default |
|----------|----------|---------|
| `CLAUDE_HOME` | Claude Code | `~/.claude` |
| `CODEX_HOME` | Codex | `~/.codex` |
| `XDG_DATA_HOME` | OpenCode | `~/.local/share` |
| `PI_SESSIONS_DIR` | Pi | `~/.pi/agent/sessions` |

OpenCode uses a centralized database at `$XDG_DATA_HOME/opencode/opencode.db` (defaults to `~/.local/share/opencode/opencode.db`).

## Status

Beta. The API may change between minor versions until 1.0.

## License

MIT
