Search when you only remember the topic
You know there was a session about rate limits. You do not remember which agent, which project, 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.
Results show recorded directories and parent or fork relationships. Codex native titles, including renamed titles, are searchable. A title-only hit is labeled title:; opening it reads the whole conversation.
Open an exact one
catchup codex/3 --all-dirs -q "rate limit"— select a ranked search result using the same query and directory scope, or use its stable ID.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 where supported, and adding --into <agent> continues it in a different agent instead.
What you will not find here. Amp is limited to locally cached conversations and omits tool results; native Amp launch and resume are unsupported. The default view is conversation, not execution. Agent handoffs can include source-marked failures, but catchup never reproduces a complete command log. Inspect the raw .jsonl/.db files when exact command output matters.
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 another project, or --all-dirs when the original directory is unknown. These flags cannot be combined.
Can I search inside a session, not just across sessions?
Yes. catchup claude --id <id> -q "deploy" reads matching exchanges from that session. If only its native title matches, catchup reads the whole conversation.
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. Add --all-dirs to search across projects too. Name an agent to narrow it, as in catchup codex --list.