agent-history

CLI tool to explore and inspect past Claude Code and Codex conversation histories from a single unified interface.

Performance

Project-aware commands keep a lightweight metadata cache so repeated runs do not need to re-parse every conversation file. By default the cache lives in the platform cache directory (~/Library/Caches/agent-history on macOS, ~/.cache/agent-history on Linux). Set AGENT_HISTORY_CACHE_DIR to override it.

The first full-project scan still has to build that cache, but repeated projects, list --here, and project-summary --here runs should be dramatically faster.

Installation

# Recommended: install globally with uv
uv tool install agent-history

# Or with pip
pip install agent-history

To install the agent skill (for Claude Code, Codex, etc.):

# Default: installs to ~/.claude/skills/
agent-history install-skill

# Custom location
agent-history install-skill -d ~/.codex/skills

Source Tagging

Results are tagged with their source:

• [c] = Claude Code (~/.claude/projects/)
• [x] = Codex (~/.codex/sessions/)

When drilling down on a specific session, you can prefix the ID to force a source:

• c:a1b2c3d4 — force Claude
• x:e5f6g7h8 — force Codex
• a1b2c3d4 — auto-detect (errors if ambiguous)

Usage

List projects

agent-history projects [--source claude|codex|all]

Shows all projects with conversation history across both backends, merged by project path.

List conversations

agent-history list [PROJECT] [-n LIMIT] [--here] [--source claude|codex|all]

• PROJECT: filesystem path, relative path (.), or name suffix
• --here: scope to the current directory's project
• Without argument: lists recent conversations across all projects

View a conversation

agent-history view SESSION_ID [-f|--full] [--no-tools] [-n LIMIT] [-o OFFSET] [--tail]

• SESSION_ID: full/partial ID, optionally prefixed with c: or x:
• -f: show full message content
• --no-tools: hide tool use details
• -n: limit messages shown
• -o: skip first N messages
• --tail: show the last N messages (use with -n)

Quick summary

agent-history summary SESSION_ID

Shows conversation metadata and a compact flow of user/assistant exchanges with tools used.

Search conversations

agent-history search QUERY [-p PROJECT] [-n LIMIT] [--here] [--source claude|codex|all]

Search conversations for a text string across both backends.

• -p PROJECT: limit search to a specific project
• --here: scope to the current directory's project

Generate catchup context

agent-history catchup SESSION_ID [-c MAX_CHARS] [--include-tools] [--from-start]

Generates a markdown summary suitable for pasting into a new session to restore context. By default it prioritizes recent conversation content and includes the final assistant message in full. Use --from-start to use start-first truncation behavior.

Project summary

agent-history project-summary [PROJECT] [-n LIMIT] [-c MAX_CHARS] [--here] [--source claude|codex|all]

Summarizes recent conversations in a project across both backends.

Export

agent-history export SESSION_ID [-f text|json]

Export conversation to simplified text or JSON format. JSON output includes a "source" field.

Print bundled skill

agent-history skill

Prints the packaged SKILL.md contents.

Common Workflows

Catching up on a previous session

# Find the session in the current project
agent-history list --here -n 10

# Get a catchup summary to paste into new context
agent-history catchup abc123def

Finding where something was discussed

# Search current project across both Claude and Codex
agent-history search "authentication bug" --here

# Search all projects
agent-history search "authentication bug"

# Search only Claude history
agent-history search "authentication bug" --source claude

Understanding project history

# Summarize current project's recent sessions
agent-history project-summary --here -n 5

# Or specify a path
agent-history project-summary /path/to/project -n 5

License

MIT