# agent-history

CLI tool to explore and inspect past Claude Code and Codex conversation histories from a single unified interface.

## Installation

```bash
# Recommended: install globally with uv
uv tool install agent-history

# Or with pip
pip install agent-history
```

To install the agent skill (for Claude Code, Codex, etc.):
```bash
# Default: installs to ~/.claude/skills/
agent-history install-skill

# Custom location
agent-history install-skill -d ~/.codex/skills
```

## Source Tagging

Results are tagged with their source:
- `[c]` = Claude Code (`~/.claude/projects/`)
- `[x]` = Codex (`~/.codex/sessions/`)

When drilling down on a specific session, you can prefix the ID to force a source:
- `c:a1b2c3d4` — force Claude
- `x:e5f6g7h8` — force Codex
- `a1b2c3d4` — auto-detect (errors if ambiguous)

## Usage

### List projects
```bash
agent-history projects [--source claude|codex|all]
```
Shows all projects with conversation history across both backends, merged by project path.

### List conversations
```bash
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

### View a conversation
```bash
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 (use with `-n`)

### Quick summary
```bash
agent-history summary SESSION_ID
```
Shows conversation metadata and a compact flow of user/assistant exchanges with tools used.

### Search conversations
```bash
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

### Generate catchup context
```bash
agent-history catchup SESSION_ID [-c MAX_CHARS] [--include-tools] [--from-start]
```
Generates a markdown summary suitable for pasting into a new 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
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
```bash
agent-history export SESSION_ID [-f text|json]
```
Export conversation to simplified text or JSON format. JSON output includes a `"source"` field.

### Print bundled skill
```bash
agent-history skill
```
Prints the packaged `SKILL.md` contents.

## Common Workflows

### Catching up on a previous session
```bash
# 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
```

### Finding where something was discussed
```bash
# 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
```bash
# 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
```

## License

MIT
