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

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

Configuration

All providers support environment variables to override default paths:

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