Conversations and search

Conversations is every Claude Code, Codex and OpenCode conversation on your machine, whether Chestnut started it or you ran the agent somewhere else, including the ones from before you installed Chestnut.

The list

Conversations are listed most recently updated first.

Each entry shows its kind (Main, Sub-agent, Named agent or Team agent), which agent it came from (Claude Code, Codex or OpenCode), the working directory it ran in, how many messages it holds, and when it was last updated. It also shows the project's colour, a breakdown of the friction found in it, and a control to analyze it. The same agent badge sits beside the title when you open a conversation, and on each session in the Notebook.

Search everything from the top bar

The search field at the top of the window searches every kind of item at once, from any screen: sessions, messages, the PRs, tickets and artifacts a session produced, Notebook days, projects and prompts. Results appear as you type, up to five of each kind, under a heading per kind. Sessions and messages join in once a word is three letters long. Sessions are ranked the way the Conversations screen ranks them: a conversation whose title, keywords or summary match comes before one that only mentions your word in a message. A PR is found by its URL or number, and also by any word in its GitHub title, such as a ticket key, once you have opened the Inspector on a session that has it. PRs a session opened before this version are found by URL and number only.

The field sits in the centre of the window. On narrow windows the name of the open screen beside the app name hides to make room. Each heading shows how many matches that kind has, each row has an icon for its kind, and the words you typed are highlighted in titles as well as snippets. A session that is open as a tab shows the same status as its card, and a PR shows its state. Each row also says when its item last changed: "5m", "3h" or "2d" within a week, then a date such as "Nov 5". A Notebook day always shows as its date, and a prompt shows no time. The X in the field clears it and also ends a Cmd+F search.

Use the Up and Down arrows to pick a result and Enter to open it, or click it. Esc closes the list. A session opens that conversation, at its best-matching message when your word was found in a message, and a message opens it at that message. A PR, ticket or artifact opens the newest session that produced it, and a Notebook day, project or prompt opens on its own screen.

Press Cmd+Enter, or pick "See all N results" at the bottom of the list, to open the Search screen. It shows every match with a count for each kind. Pick a kind to page through all of its results, narrow by project or date, and sort by Best match or Newest. Each result says when it last changed, as "2 hours ago" within a week and as a date after that. Each matching message is its own row with your words highlighted.

Press Cmd+F to jump to the field. In an open conversation it starts limited to that conversation: a tag shows its name, a count such as 3 of 12 shows which match you are on, and Enter and Shift+Enter step through the matches as the conversation scrolls to each one. With a terminal focused it searches everything, and nothing you type reaches the session; to search one session's full text, open its conversation. Press Backspace in the empty field to remove the tag and search everything, or Cmd+Shift+F to open the field without one. Esc ends the search and puts you back where you were.

Search in Conversations

The search box in Conversations runs a full-text search across conversation titles, project paths, message content, keywords, and generated summaries. It searches the database on your machine, so it works offline and covers your whole history rather than a recent window.

A conversation whose title, keywords or summary match comes first; after those come conversations that match only in their messages or project path, best match first. Every result is labelled with its kind: Main, Sub-agent, Named agent or Team agent.

Filters beside the search box narrow the list and the results:

• Type: your own conversations (the default), all conversations, or only the background work Chestnut ran for you: all of it, or just summaries, friction analysis or project discovery.
• Project, to one directory.
• Date range, either a preset like the last 7 days or a custom range.
• Session kinds: which kinds are listed and searched. Main only by default; tick Sub-agent, Named agent or Team agent to include them too.

An active filter shows its value and an X that resets it.

Reading a conversation

Opening a conversation gives you three tabs.

Messages is the full transcript, oldest first. Older messages load as you scroll up, and an arrow button jumps back to the newest. Message kinds are colour coded so you can tell your own turns from the agent's replies, from tool output, and from subagent work.

Timeline is a generated overview: a summary of what the conversation was about, the phases it moved through, and the keywords pulled out of it. If a conversation has no summary yet, the Timeline tab has an Analyze button to generate one. Summaries are worth generating for long sessions you expect to come back to, because they are searchable too.

Friction lists points where the conversation went badly: retries, dead ends, and corrections. Each item can be acted on, which is covered in Tasks, actions, and notes.

The panel on the right of the conversation says Up to date or how many messages behind the summary is, so you know whether the overview covers the latest work. Choose Re-analyze there to bring it up to date.

Background work

Chestnut also writes summaries for you, if you left that on when you set it up. Your main sessions are summarised as they grow, without you pressing anything. Every summary runs a background session on your own plan, so if you would rather ask for each one yourself, turn automatic summaries off in Settings > Analysis. Analyze keeps working either way, on any session.

If your agent's usage limit runs out while it writes a summary, Chestnut pauses automatic summaries until the limit resets, and Settings > Analysis says until when. When your agent does not say when the limit resets, they start again once one of your own sessions on that agent gets a reply. Analyze still works during the pause and shows the limit error if the limit still holds.

Background sessions run on the agent chosen on the Automations screen during setup. To change it, use Background agent in Settings > Analysis: Claude Code, Codex or OpenCode. All three are always listed. If you pick one that is switched off under Settings > CLI backends, the picker warns that background work will fail until you switch it on.

To run one kind of background work on a different agent, open Advanced under that picker and choose an agent for it; each kind starts on Same as background agent. The summaries and Notebook descriptions name the agent that runs each and whose plan it uses. Because a different plan pays, automatic summaries and the Notebook each wait for their own switch, named for the agent: for example Allow summaries on Codex in Settings > Analysis and Allow the Notebook on Codex in Settings > Notebook. Claude Code's switches appear only until you allow it.

If Codex runs any of your background work and one of your Codex hooks is waiting for review, background work cannot start on its own: Codex would stop on its "Hooks need review" screen, which only you can answer. Settings > Analysis names each waiting hook. To fix it, run codex in a terminal and review them with /hooks. The next background run checks again.

If a background Claude run has not started 30 seconds after launch, Chestnut stops it, because Claude is waiting on a startup question nobody can see. The error names the folder it was in. Run claude in that folder from a terminal, answer its question, then try again.

Picking a conversation back up

The panel on the right of an open conversation (beside the title on a narrow window) starts with an Open in control that names the conversation's agent: Open in Claude Code, Open in Codex or Open in OpenCode.

The main action reopens the conversation as a session tab inside Chestnut, on the agent it ran on and in the same working directory. If a tab for that conversation is already open, Chestnut moves you to it rather than starting a second copy.

The menu next to it has Open in iTerm2, for when you would rather work outside the app (without iTerm2 installed, it uses Terminal). It runs the agent the conversation ran on, with that agent's own arguments: claude --resume, codex resume or opencode --session. Choosing it twice opens two tabs, not one. If that agent's command is not installed, Chestnut says so instead of opening anything. An OpenCode conversation you started inside Chestnut cannot be opened this way either, because Chestnut keeps its history in a database of its own that opencode in another terminal does not read; open it in Chestnut instead. The same menu has Open in terminal and Open in Finder at the conversation's directory, and Copy path.

Resuming a conversation that belongs to a project runs in that conversation's own directory, and the project's arguments for that agent still apply.

Keeping a copy

Claude Code deletes its own old transcripts after a while, so Chestnut's copy may be the only one left. Settings > Backup & storage saves a complete copy of Chestnut's database, or a zip with every conversation as its own file, wherever you choose. It can also clear out old conversations: preview what would be removed, then confirm. The preview says how many of them exist only in Chestnut; for those, removal is permanent, because the agent has already deleted its own copy.

Where to go next

Tasks, actions, and notes covers what Chestnut does with the friction it finds.