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

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.

Codex normally stores these databases under ~/.codex. If Codex uses a custom home, set CODEX_HOME; the CLI and Sharingan reader honor it. Codex's legacy_to_paginated_v1 migration moved thread metadata and transcripts into the two SQLite databases and removed successfully migrated rollout JSONLs. The CLI still scans remaining rollout files for sessions the migration skipped, and deduplicates them against SQLite thread IDs. SQLite reads are read-only; the CLI also checks WAL sidecars when refreshing its cache.

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:

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

Finding a past conversation

1. Run agent-sessions with appropriate filters to find the session
2. Use --context <session-id> if you need a compact handoff block
3. For Claude sessions: use claude --resume <id> to continue, or claude-history to browse
4. 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