Search when you only remember the topic
You know there was a session about rate limits. You do not remember which agent, or when:
-q implies --list, so it prints the matching sessions rather than dumping one. -n 50 raises the listing cap from its default of 20.
Open an exact one
catchup claude/3— the third-newest Claude Code session here.catchup --id <id>— an exact session id, as printed by the listing.catchup codex -i— metadata only, to confirm you have the right one before reading it.catchup claude --dir ~/src/proj— sessions belonging to another directory.
Read it, or pick the work back up
Reading prints clean Markdown — your messages and the agent's replies, with tool calls, command output, and reasoning traces stripped:
To continue the work rather than read it, hand the same selection to fork: catchup fork --id <id> resumes through the agent's native path, and adding --into <agent> continues it in a different agent instead.
What you will not find here. catchup reads conversation, not execution. Tool calls, command output, and reasoning traces are deliberately stripped, so it is the wrong tool for auditing what a command actually returned — grep the agent's raw .jsonl/.db files for that.
Questions
Where does catchup look for sessions?
In each agent's own local history, scoped to the directory you run it in. Use --dir <path> to read the sessions belonging to a different project directory instead of the current one.
Can I search inside a session, not just across sessions?
Yes — stdout is the wire format, so pipe it: catchup claude | rg -C3 "deploy". The -q flag narrows which session, and a pager or grep narrows what inside it.
Does searching work across different agents at once?
Yes. catchup --list covers recent sessions from every supported agent in the current directory, so you do not have to remember which agent you used. Name an agent to narrow it, as in catchup codex --list.