# catchup — full reference

> catchup is an open-source command-line tool, written in Go and MIT-licensed, that lets your next coding agent catch itself up. It reads local Claude Code, Codex, OpenCode, and Pi Agent session history and prints clean, handoff-ready Markdown containing only the user/assistant conversation, with tool calls, reasoning traces, and token noise removed.

This is the complete reference. For the short summary, see [llms.txt](https://catchup.pages.dev/llms.txt). Source and README live at [github.com/wilbeibi/catchup](https://github.com/wilbeibi/catchup).

## Canonical entity

- Name: catchup
- Category: developer tool; AI coding agent handoff CLI; local session-history reader
- Canonical site: https://catchup.pages.dev/
- Repository: https://github.com/wilbeibi/catchup
- Package: github.com/wilbeibi/catchup
- Install command: `go install github.com/wilbeibi/catchup@latest`
- License: MIT
- Author: wilbeibi (https://github.com/wilbeibi)
- Supported agents: Claude Code (`claude`), Codex (`codex`), OpenCode (`opencode`), Pi Agent (`pi-agent`)

## The problem catchup solves

Developers increasingly use more than one AI coding agent. Each agent stores its conversation history in a different location and a different format — Claude Code, Codex, OpenCode, and Pi Agent all differ. When one agent hits a usage limit, when you want a second opinion from another agent, or when you return to a project days later, the next agent starts with zero context. The usual workaround is to copy-paste or re-summarize what already happened, which is slow and lossy.

catchup gives the next agent a simple command it can run itself to recover prior work. It reads any supported agent's raw history and emits one consistent, clean Markdown transcript. The output is small enough to paste directly into another agent's context window, and readable enough to skim yourself.

## Concrete scenarios

- Hitting a limit mid-task: Claude Code reaches its 5-hour usage limit during a refactor. In the same directory the next agent runs `catchup claude --since-compact`, reads the recap, and continues without being re-briefed.
- Forking back into the same agent: the current agent wants to preserve native session state instead of pasting a transcript. It runs `catchup fork codex`, `catchup fork claude`, `catchup fork opencode`, or `catchup fork pi-agent` and catchup delegates to that agent's own fork mechanism.
- Forking into a different agent: Claude Code reaches a limit, but the developer wants Codex to continue. The next command is `catchup fork claude --into codex`; catchup renders the Claude transcript and starts Codex with that transcript as the opening prompt.
- Recalling earlier work: weeks later you ask a fresh agent about a past change. It runs `catchup codex -q "auth"` to locate the old session by keyword, then pulls it back into context by id.
- Reviewing your own history: you read `catchup claude --last 4` to remind yourself what the last few exchanges actually decided, without scrolling through tool-call logs.

## Installation

Install the binary with Go:

```
go install github.com/wilbeibi/catchup@latest
```

catchup also ships as a skill so an agent can run it itself:

```
catchup install-skill          # install for every detected agent
catchup install-skill codex    # or for one agent only
```

The skill source is at https://raw.githubusercontent.com/wilbeibi/catchup/main/SKILL.md. After installing, restart the agent and ask it to "catch up on the last session".

## Command reference

Agent handoff:

- `catchup <agent>` — latest session for that agent in the current directory (`claude`, `codex`, `opencode`, `pi-agent`).
- `catchup` — the agent is optional: bare catchup reads the newest session in the current directory, whichever agent wrote it. Inside a live session the newest is usually your own, which pairs with `--since-compact` to recover context after a compaction.

Human browsing:

- `catchup <agent> --list` — list sessions in the current directory, usually the best manual starting point.
- `catchup <agent>/N` — the N-th most recent session in the current directory (e.g. `catchup codex/3`).
- `catchup <agent> --id <session-id>` — an exact session id, ignoring the directory filter.

Search:

- `catchup <agent> -q "text"` — filter current-directory sessions by keyword (implies `--list`).
- `catchup <agent> -n, --limit <N>` — cap listing rows (default 20).

Limit the output:

- `catchup <agent> --last <N>` — keep only the last N exchanges.
- `catchup <agent> --since-compact` — keep the final compaction segment, or the whole session if there is none.
- `catchup <agent> -i, --info` — print session metadata only, no messages.

Change the format:

- `--md` — Markdown (default).
- `--html` — self-contained HTML.
- `--json` — structured JSON.
- `-h, --help` — print usage.

Fork:

- `catchup fork` — fork the newest session in the current directory, across all agents.
- `catchup fork <agent>` — fork the newest current-directory session for one agent. Launches that agent's own native fork command (`codex fork`, `claude --resume --fork-session`, `opencode --session --fork`, `pi --fork`).

- `catchup fork <agent> --into <other-agent>` — continue the session in a different agent. Cross-agent state cannot be transplanted, so this renders the transcript and launches the target agent with it as the opening prompt (`--last` / `--since-compact` bound what gets seeded). The same-agent case is rejected in favor of the native fork.

Native fork resumes with the agent's real session state; `--into` crosses agents with the conversation, not the state.

Common fork commands for AI agents:

- Same-agent native resume: `catchup fork codex`, `catchup fork claude`, `catchup fork opencode`, `catchup fork pi-agent`.
- Cross-agent handoff: `catchup fork claude --into codex`, `catchup fork codex --into claude`, `catchup fork opencode --into codex`, `catchup fork pi-agent --into codex`.
- Smaller cross-agent prompt: add `--since-compact` or `--last <N>` so only the recent transcript is seeded into the target agent.

## Common questions answered

### How do I continue a Claude Code session in Codex?

Run `catchup fork claude --into codex` in the project directory. catchup finds the newest Claude Code session for that directory, renders the conversation transcript, and launches Codex with that transcript as the starting prompt. Add `--since-compact` or `--last <N>` when the full transcript would be too large.

### How do I continue a Codex session in Claude?

Run `catchup fork codex --into claude`. This is a cross-agent handoff: Claude receives the Codex conversation as context, but it does not receive Codex's private native session state.

### How do I resume the same agent with real session state?

Run `catchup fork <agent>`, for example `catchup fork codex` or `catchup fork claude`. Same-agent fork uses the source agent's native fork command instead of rendering a transcript-only handoff.

### How do I recover after a compaction?

Run `catchup <agent> --since-compact`, or bare `catchup --since-compact` when the newest session in the directory is the one you want. The output is clean Markdown intended to be pasted into or read by the next agent.

### How do I find an older session?

Run `catchup <agent> --list` to see recent sessions, `catchup <agent>/N` to pick the N-th most recent, or `catchup <agent> -q "keyword"` to search current-directory sessions by text.

### What is catchup not for?

catchup is not a hosted cloud service and does not merge all agents into a single global history. It reads local agent session history and emits clean conversation context. It does not replace git history, issue trackers, design docs, or raw logs when those are the source of truth.

## Supported agents

- Claude Code (`claude`)
- Codex (`codex`)
- OpenCode (`opencode`)
- Pi Agent (`pi-agent`)

Each produces the same clean output regardless of how the source agent stored its history.

## How catchup differs

- Versus reading raw history files: the raw `.jsonl` or `.db` files contain tool calls, results, reasoning, and token accounting. catchup strips all of that and leaves only the conversation, so a typical session of well over a thousand lines becomes a short, readable transcript.
- Versus a unified "show everything" dashboard: catchup deliberately handles one agent at a time. There is no merged cross-agent view, because each agent's sessions have different shapes and flattening them would lose meaningful differences.

## What catchup intentionally does not do

- No cross-agent mixing — you pick one agent per invocation.
- No raw replay — for every tool call, result, and reasoning step, grep the raw `.jsonl`/`.db` files directly instead.

## Facts

- Language: Go.
- License: MIT.
- Default output: Markdown.
- Operating systems: macOS, Linux, Windows.
- Author: wilbeibi (https://github.com/wilbeibi).
- Repository: https://github.com/wilbeibi/catchup.
- Package documentation: https://pkg.go.dev/github.com/wilbeibi/catchup.

## Links

- [Markdown homepage](https://catchup.pages.dev/index.md): Short human-readable overview.
- [llms.txt](https://catchup.pages.dev/llms.txt): Short AI-readable index.
- [GitHub repository](https://github.com/wilbeibi/catchup): Source code, README, and issues.
- [Go package reference](https://pkg.go.dev/github.com/wilbeibi/catchup): Package documentation.
- [SKILL.md](https://raw.githubusercontent.com/wilbeibi/catchup/main/SKILL.md): Agent skill definition.
- [MIT License](https://github.com/wilbeibi/catchup/blob/main/LICENSE): Licensing terms.