Agent Sessions

Search and manage AI coding agent conversation history across Claude Code, Codex CLI, Gemini CLI, opencode, Hermes Agent, and Cline CLI.

$ARGUMENTS

Skill path resolution

When the skill catalog shows a path such as r0/agent-sessions/SKILL.md, treat r0 as a skill-root alias and resolve it from the current session's Skill roots table first. Do not prepend the alias literally to the filesystem path. The resolved path is:

<resolved-skill-root>/agent-sessions/SKILL.md

The installed copy may be a symlink to the source repository; inspect the resolved target before editing or reinstalling the skill.

Tools Available

CLI: `agent-sessions`

Located at /Users/vladmdgolam/Play/radar/tools/agent-sessions. A Python 3 script that reads session data from all supported agents.

# List all recent sessions (default 30)
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions

# Filter by agent
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --agent claude
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --agent codex
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --agent gemini
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --agent opencode
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --agent hermes
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --agent cline

# Title/prompt search first (AND logic, case-insensitive; token-efficient)
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --search "metal shader" --search-scope titles --limit 10

# Deep full-transcript search only when title/prompt search misses
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --search "metal shader" --search-scope full --limit 10

# Filter by project name or path
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --project radar

# Combine filters
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --agent claude --project aino --search "auth" --search-scope titles --limit 10

# Compact JSON output (for parsing; omits full transcript search_text)
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --json --limit 10

# Include full transcript search_text only if you need client-side full-text search
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --json --include-search-text --limit 10

# Copy compact context for one or more sessions
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --context <session-id>
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --context <id-1> <id-2>

# Build a compact evidence pack for one or more sessions
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --pack <id-1> <id-2> --max-chars 5000

# Read bounded excerpts, optionally around a topic/query
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --read <id-1> <id-2> --query "logo rotation" --max-chars 5000

# Extract only the user's messages
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --read <id-1> <id-2> --role user --max-chars 5000

# Resume a Claude Code session
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --resume <session-id>

# Control result count; prefer small limits unless the user asks for a broad scan
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --limit 10

TUI: `claude-history`

Located at ~/.local/bin/claude-history. Rust-based fuzzy search TUI for Claude Code sessions only.

# Interactive fuzzy search across all Claude sessions
claude-history

# Scoped to current project
claude-history --local

# View a specific session file
claude-history /path/to/session.jsonl

# Resume selected session
claude-history --resume

# Fork from a past session
claude-history --fork-session

GUI: Claude Code History Viewer (CCHV)

Desktop app at /Applications/Claude Code History Viewer.app. Supports 7 agents (Claude, Codex, Gemini, Cursor, Cline, Aider, OpenCode) with analytics, cost tracking, and full-text search.

open "/Applications/Claude Code History Viewer.app"

Data Sources

Agent	Location	Format
Claude Code	`~/.claude/projects/<encoded>/*.jsonl`	JSONL with `type`, `message`, `cwd`, `sessionId`, `timestamp`
Codex CLI	`~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`	JSONL with `session_meta` (payload.id, payload.cwd) and `response_item` entries
Gemini CLI	`~/.gemini/tmp//chats/session-.json`	JSON with `sessionId`, `startTime`, `messages[]` array
opencode	`~/.local/share/opencode/opencode.db`	SQLite tables: `session`, `message`, `part`, `project`
Hermes Agent	`~/.hermes/state.db`	SQLite tables: `sessions`, `messages`
Cline CLI	`~/.cline/data/db/sessions.db` + `~/.cline/data/sessions//.messages.json`	SQLite session index plus JSON message transcripts

Project mapping for Gemini: ~/.gemini/projects.json maps absolute paths to project names.

Cline sessions created with cline --data-dir <path> can be included by setting AGENT_SESSIONS_CLINE_DATA_DIRS to a colon-separated path list.

Workflow

First move: never spelunk by hand

If the user asks to read, continue, summarize, compare, or inspect an agent conversation, start with this CLI. Do not begin with broad find ~, manual SQLite queries, or copying live agent databases unless this CLI fails.

For explicit session ids, go straight to a pack:

python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --pack <session-id> --max-chars 8000

For "latest conversation in this folder/project":

python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --project "$PWD" --limit 5
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --pack <top-session-id> --max-chars 8000

For "last messages" or "where did it leave off", prefer --pack first; it is designed to include recent excerpts. Use --read --query "topic" for focused follow-up.

Token-efficient retrieval ladder

Use the smallest useful output first:

Start with table output and a small limit: --limit 10.
Add --agent and/or --project whenever the user gave a clue.
Search titles/prompts first: --search "query" --search-scope titles.
Fall back to --search-scope full only if title search misses.
Use --json only when you need structured parsing; it is compact by default.
Do not use --include-search-text unless building a UI/client-side index or explicitly inspecting transcript text.
For handoff context, prefer --context <id...> instead of pasting full JSON.
When the user gives session refs and asks to compare, infer, summarize, or conclude from them, run --pack <id...> first.
If the pack is too broad or the user gave a topic, run --read <id...> --query "topic" for focused excerpts.
If the user asks for only their own prompts/messages, add --role user.

Finding a past conversation

Run agent-sessions with appropriate filters to find the session
Use --context <session-id> if you need a compact handoff block
For Claude sessions: use claude --resume <id> to continue, or claude-history to browse
For viewing any agent's full conversation: open CCHV

Reading provided session refs

If the user pastes blocks like:

agent: codex
session id: 019ee05b-25d6-7153-83af-aee3a848e472
session title: ...

Extract the IDs and start with:

python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --pack 019ee05b-25d6-7153-83af-aee3a848e472 <other-id> --max-chars 5000

Use the pack as evidence for cross-session conclusions. If the user asks about a specific topic, use:

python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --read <id-1> <id-2> --query "topic terms" --max-chars 5000

If the user only wants their own messages/prompts:

python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --read <id-1> <id-2> --role user --max-chars 5000

Avoid dumping full transcripts unless the user explicitly asks for exhaustive review.

Answering "what did I work on?"

# Recent activity across all agents
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --limit 20

# Specific project
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --project bloom-metal --limit 20

# Specific agent
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --agent codex --limit 20

Resuming a session

# Find the session
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --search "shader bug" --search-scope titles --agent claude --limit 10

# Resume it (Claude only)
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --resume <session-id>
# This execs into: claude --resume <session-id>

JSON Output Schema

When using --json, each session object has:

{
  "agent": "claude|codex|gemini|opencode|hermes|cline",
  "session_id": "uuid",
  "prompt": "first user message (truncated to 120 chars)",
  "timestamp": "ISO 8601",
  "project_path": "/absolute/path/to/project",
  "project_name": "project-dir-name",
  "session_file": "/path/to/session/file"
}

--json omits search_text by default. Pass --include-search-text only for full-text indexing/search clients.

Context Output

--context <session-id> emits compact pasteable context:

agent: opencode
session id: n
session title: K

Multiple IDs emit a list with the same fields.

Pack And Read Output

--pack <id...> emits one bounded evidence pack per session: metadata, brief, key user requests, and recent or query-relevant excerpts.

--read <id...> emits bounded transcript excerpts. For long transcripts it includes an initial orientation excerpt plus a Recent Excerpts tail so "last messages" are not crowded out. Add --query "terms" to return message windows around relevant matches instead of broad excerpts.

Add --role user to output/search only user messages, or --role assistant for assistant-only excerpts. Default is --role all.

Useful controls:

--role user            # only user messages
--max-chars 5000        # approximate excerpt budget per session
--last-turns 8          # recent messages included in packs/overflow reads
--context-messages 2    # messages before/after each query match

agent-sessions