claude-history

CLI tool to explore and inspect past Claude Code and Codex conversation histories.

Installation

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

# Or with pip
pip install claude-history

This package installs two CLIs:

• claude-history for ~/.claude/projects/
• codex-history for ~/.codex/sessions/

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

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

# Custom location (e.g., for Codex)
claude-history install-skill -d ~/.codex/skills

To install the Codex skill:

codex-history install-skill

Usage

List projects

claude-history projects

Shows all projects with conversation history, conversation counts, and last modified dates.

List conversations in a project

claude-history list [PROJECT] [-n LIMIT]

• PROJECT: Can be specified in multiple formats:
  • Relative path: . (current directory), .., ./subdir
  • Full filesystem path: /Users/bob/myproject
  • Project name suffix: myproject (matches any project ending with that name)
  • Path as shown by projects command: /Users/bob/myproject
• Without argument: lists recent conversations across all projects

View a conversation

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

• SESSION_ID: Full ID, partial ID (e.g., first 8 chars), or file path
• -f: Show full message content (not truncated)
• --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

claude-history summary SESSION_ID

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

Search conversations

claude-history search QUERY [-p PROJECT] [-n LIMIT]

Search conversations for a text string.

• -p PROJECT: Limit search to a specific project (supports ., .., full paths, or name suffix)
• Without -p: searches all conversations across all projects

Generate catchup context

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

Generates a markdown summary suitable for pasting into a new Claude 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

claude-history project-summary PROJECT_PATH [-n LIMIT] [-c MAX_CHARS]

Summarizes recent conversations in a project.

Export

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

Export conversation to simplified text or JSON format.

Print bundled skill

claude-history skill

Prints the packaged SKILL.md contents.

Codex Usage

codex-history has the same command surface as claude-history and is tuned for Codex session files and project organization. Use CODEX_HISTORY_DIR to override the default ~/.codex/sessions/ location.

List Codex projects

codex-history projects

List Codex conversations

codex-history list [PROJECT] [-n LIMIT]

View/search/summarize Codex sessions

codex-history view SESSION_ID
codex-history search "query" [-p PROJECT]
codex-history summary SESSION_ID
codex-history catchup SESSION_ID
codex-history project-summary PROJECT
codex-history export SESSION_ID
codex-history skill

Common Workflows

Catching up on a previous session

# Find the session (use . for current directory)
claude-history list . -n 10

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

Finding where something was discussed

# Search current project
claude-history search "authentication bug" -p .

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

Understanding project history

# Summarize current project's recent sessions
claude-history project-summary . -n 5

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

License

MIT