# claude-history

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

## Installation

```bash
# Install with uv
uv pip install -e .

# Or with pip
pip install -e .
```

To also install the agent skill:
```bash
./install.sh              # Installs to ~/.claude/skills/
./install.sh /custom/path # Installs to custom location
```

## 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:
  - 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]
```
- `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

### 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 [-n LIMIT]
```
Search all conversations for a text string.

### Generate catchup context
```bash
claude-history catchup SESSION_ID [-c MAX_CHARS] [--include-tools]
```
Generates a markdown summary suitable for pasting into a new Claude session to restore context.

### 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.

## Common Workflows

### Catching up on a previous session
```bash
# Find the session
claude-history list /path/to/project -n 10

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

### Finding where something was discussed
```bash
claude-history search "authentication bug"
```

### Understanding project history
```bash
claude-history project-summary /path/to/project -n 5
```

## License

MIT
