---
name: claude-history
description: |
  CLI tool to explore and inspect past Claude Code 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 conversation history
  - The user wants to resume work from a previous session and needs context
---

# Claude History CLI

A tool to explore past Claude Code conversations stored in `~/.claude/projects/`.

## Installation

```bash
# Install from PyPI
pip install claude-history

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

# Install to a custom location (e.g., for Codex)
claude-history install-skill -d ~/.codex/skills
```

## Commands

### 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]
```
- `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 [-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]
```
Generates a markdown summary suitable for pasting into a new Claude session to restore context. Output goes to stdout.

### Project summary
```bash
claude-history project-summary PROJECT_PATH [-n LIMIT] [-c MAX_CHARS]
```
Summarizes recent conversations in a project - useful for understanding project history across sessions.

### 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 (use . for current directory)
claude-history list . -n 10

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

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