agent-chat-reader 0.1.5

Read and search Codex CLI and Claude Code chat history from the terminal.

agent-chat-reader

Read and search Codex CLI and Claude Code chat history from the terminal.

Useful for AI agents that need to recall what was discussed or decided in past sessions, without manually parsing noisy JSONL files.

Install

uv tool install agent-chat-reader

Or for development:

git clone https://github.com/alik-git/agent-chat-reader
cd agent-chat-reader
uv sync --extra dev
uv run agent-chat-reader --help

Usage

List recent sessions (both Codex and Claude Code, sorted by recency):

agent-chat-reader --list

Search across all sessions for a keyword:

agent-chat-reader --find "sim2sim"
agent-chat-reader --find "policy_interface" --source codex
agent-chat-reader --find "side chat phrase" --source codex-side

Read a specific session by UUID prefix:

agent-chat-reader 019eaecb
agent-chat-reader 1bfc739b --verbose     # include tool call summaries
agent-chat-reader 019eaecb --tail 5      # last 5 user turns only
agent-chat-reader 019eaecb --hide-timestamps
agent-chat-reader 019eaecb --format json

What it filters out

The raw JSONL files are very noisy. This tool extracts only:

• Codex: user_message events, agent_message events, and full response_item assistant text. Guardian/subagent sessions (auto-approval bots) are hidden by default.
• Codex side chats: user submissions and assistant text reconstructed from the local Codex runtime log database. Known internal helper sessions are hidden by default.
• Claude Code: real user turns (not tool-result carriers), and assistant text blocks (not thinking blocks or tool calls). Sidechain sub-agent turns are hidden by default.

Use --include-subagents to see everything.

Options

Flag	Description
--list / -l	List recent sessions from both sources
--find KEYWORD / -f	Search all sessions for a keyword
--source codex|codex-side|claude	Filter to one source. codex includes normal Codex sessions and side chats
--verbose / -v	Include brief tool call summaries (Claude sessions)
--tail N / -n N	Show only the last N user turns of a session
--include-subagents	Include guardian/subagent sessions
--format text|json	Output format for session reads
--hide-timestamps	Hide message timestamps and elapsed-gap labels
--limit N	Max sessions shown by --list (default: 40)

Session reads show timestamps by default. Elapsed labels use the current speaker's role, such as (agent took 8s) or (user took 4m), and only report the time since the previous visible message.

Use --format json when another agent or script needs stable structured fields instead of terminal separators. JSON turns include timestamp, local_time, elapsed_seconds, role, and text.

Session storage locations

Agent	Path
Codex CLI	~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl
Codex side chats	~/.codex/logs_2.sqlite
Claude Code	~/.claude/projects/*/*.jsonl

Codex side chats are log-backed rather than normal rollout transcripts, so the tool labels them as codex-side in list and search output.

Development

uv run ruff format --check .
uv run ruff check .
uv run mypy
uv run pytest
uv build