agent-sessions 0.2.0

Discover and inspect local AI coding agent sessions

agent-sessions

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

Looking for a ready-made supervision tool? Check out Tether.

Install

pip install agent-sessions

Usage

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