vladmdgolam Agent Sessions
Search and manage AI coding agent conversation history across Claude Code, Codex CLI, Gemini CLI, opencode, Hermes Agent, and Cline CLI.
$ARGUMENTS
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
--agentand/or--projectwhenever the user gave a clue. - Search titles/prompts first:
--search "query" --search-scope titles. - Fall back to
--search-scope fullonly if title search misses. - Use
--jsononly when you need structured parsing; it is compact by default. - Do not use
--include-search-textunless 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-sessionswith 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, orclaude-historyto 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