# claude-history

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

## Installation

```bash
# 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.):
```bash
# 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:
```bash
codex-history install-skill
```

## Usage

### List projects
```bash
claude-history projects
```
Shows all projects with conversation history, conversation counts, and last modified dates.

### List conversations in a project
```bash
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
```bash
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
```bash
claude-history summary SESSION_ID
```
Shows conversation metadata and a compact flow of user/assistant exchanges with tools used.

### Search conversations
```bash
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
```bash
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
```bash
claude-history project-summary PROJECT_PATH [-n LIMIT] [-c MAX_CHARS]
```
Summarizes recent conversations in a project.

### Export
```bash
claude-history export SESSION_ID [-f text|json]
```
Export conversation to simplified text or JSON format.

### Print bundled skill
```bash
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
```bash
codex-history projects
```

### List Codex conversations
```bash
codex-history list [PROJECT] [-n LIMIT]
```

### View/search/summarize Codex sessions
```bash
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
```bash
# 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
```bash
# Search current project
claude-history search "authentication bug" -p .

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

### Understanding project history
```bash
# 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
