---
name: codex-history
description: |
  CLI tool to explore and inspect past Codex conversation histories. Use this skill when:
  - You need to catch up on a previous Codex session that ran out of context
  - You want to review what was discussed or accomplished in past Codex sessions
  - You need to search across Codex history for specific topics
  - The user asks about their Codex conversation history
---

# Codex History CLI

A tool to explore past Codex conversations stored in `~/.codex/sessions/`.

## Installation

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

# Install the Codex skill (default: ~/.codex/skills/)
codex-history install-skill
```

## Commands

### List projects
```bash
codex-history projects
```
Shows all projects (derived from session working directories), conversation counts, and last modified dates.

### List conversations in a project
```bash
codex-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)
- Without argument: lists recent conversations across all projects

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

### Search conversations
```bash
codex-history search QUERY [-p PROJECT] [-n LIMIT]
```
Search conversations for a text string.
- `-p PROJECT`: Limit search to a specific project
- Without `-p`: searches all conversations

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

### Project summary
```bash
codex-history project-summary PROJECT_PATH [-n LIMIT] [-c MAX_CHARS]
```
Summarizes recent conversations in a project.

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