agent-history

name

agent-history

description

CLI tool to explore and inspect past Claude Code and Codex conversation histories. Use this skill when: - You need to catch up on a previous conversation that ran out of context - You want to review what was discussed or accomplished in past sessions - You need to search across conversation history for specific topics - You want to generate a summary of past work to paste into a new session - The user asks about their Claude Code or Codex conversation history - The user wants to resume work from a previous session and needs context

Agent History CLI

A unified tool to explore past Claude Code (~/.claude/projects/) and Codex (~/.codex/sessions/) conversations from a single interface.

Installation

pip install agent-history

# Install the skill (default: ~/.claude/skills/)
agent-history install-skill

Source Tagging

Results are tagged with their source:

• [c] = Claude Code
• [x] = Codex

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

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

Commands

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
• Results are interleaved by modification time and tagged with [c]/[x]

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

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
• Results are tagged with [c]/[x]

Generate catchup context

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

Generates a markdown summary suitable for pasting into a new session to restore context.

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.

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 > catchup.md

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