Agents driving Chestnut

Sessions that drive the app

Every session you run in Terminal is an ordinary Claude Code, Codex or OpenCode session. What is not ordinary is that Chestnut can hand each one a set of tools for reading and driving the app it runs inside. All three agents get the same tools.

Once a session has those tools, the session list stops being something only you maintain: sessions take over housekeeping you would otherwise do by hand.

What a session can do

• Report its own status. A session can set its tab's title, the progress caption under that title, and the tab colour. A glance at the session list tells you what each one is doing without opening it.
• Show what it made. A session can list the pages, files and links it produced in the Inspector beside its terminal, so they do not scroll away.
• Open new sessions. Ask a session to start another one, in the same project or a different one, or to reopen an earlier conversation and carry on where it stopped. A new session runs the same agent as the Chestnut session that asked for it, unless you ask for Claude Code, Codex or OpenCode by name. A reopened conversation always runs on the agent it started with.
• Search your history. A session can search the conversations in your Chestnut history and read the matching passages back, so past work feeds into new work without you hunting for it. It can also look up where past sessions went wrong, and export whole conversations to markdown files.
• Read your Notebook. A session can read your daily Notebook entries, so "what did I do on Tuesday" has an answer.
• Tidy the session list. A session can reorder, group, and collapse the tabs in the session list, which is useful when it has just opened several of them.
• Add to Quick Launch. A session can add a Quick Launch button that starts a prepared session with a click, handy for work you kick off the same way every time.

There is more behind these, but they are where most people start.

When a session renames itself, the session list shows the new title. For a Codex or OpenCode session, Chestnut renames the session inside the agent too. A Codex session takes the new name once it has finished its first turn and is idle with nothing typed.

What a session can change

The same tools let a session act on things you might care about. It can type into or interrupt other sessions, end them, rename or recolour any session, change your Quick Launch buttons, export conversations to files, and delete projects. Every change happens in the app in front of you, where you can see it. Ending a session stops its work, though its conversation is kept and can be reopened. Deleting a project cannot be undone, though its conversations stay in your history.

Some changes wait for you. When a session asks to change how a project launches, to start a session with arguments the project has not been approved for, or to start one with arguments it does not run with itself (for example another project's), an amber chip appears in the title bar, counting what waits. It never interrupts what you are doing. Click it to open the list of waiting requests, each naming exactly what was proposed. Nothing happens until you choose Approve, and closing the list leaves every request waiting. A chestnut:// link that starts a Quick Launch button opens that list on itself, and starts nothing until you choose Launch.

Switching it on

The tools come as an MCP server (the standard way these agents add tools), which ships inside the app. Chestnut must be running for the tools to work, since they talk to the live app, and everything stops the moment Chestnut is not running. A session started inside Chestnut has the server when you connected that agent, on first run or in Settings > Agent integration; one you start elsewhere gets it the way its agent adds servers.

Claude Code

A Claude Code session started from the Terminal view has the tools from its first turn, as long as Claude Code is connected in Settings > Agent integration. There is nothing to register. Chestnut sets them up for that one session only, in place of any Chestnut server you registered yourself, so your own Claude Code setup is unchanged outside Chestnut.

A Claude Code session you start in another terminal does not know about Chestnut until you register the server with Claude Code once, from any terminal:

claude mcp add -s user chestnut /Applications/Chestnut.app/Contents/Resources/chestnut-mcp/chestnut-mcp

Then restart Claude Code. The registration applies to every Claude Code session you run outside Chestnut. If that trade sounds wrong for your setup, leave the server unregistered: sessions inside Chestnut keep the tools either way, while Claude Code is connected.

Codex and OpenCode

A Codex or OpenCode session started from the Terminal view has the tools from its first turn, as long as that agent is connected in Settings > Agent integration. There is nothing to register. Chestnut sets them up for that one session only, so your own Codex and OpenCode setup is unchanged outside Chestnut. A Codex session can call the tools without asking you to approve each call.

A Codex or OpenCode session you start in another terminal does not know about Chestnut until you connect the two. You do this once per agent, from Settings: open CLI backends. The Codex and OpenCode cards each have a Connect Chestnut to Codex or Connect Chestnut to OpenCode row with a Connect button.

Pressing Connect shows the exact command Chestnut will run, before it runs anything. The command adds Chestnut to that agent's own settings. If the agent already has an MCP server named chestnut, it is replaced. Press Connect again to run it, or Cancel to leave your settings untouched.

For Codex, the same registration also works by hand from any terminal:

codex mcp add chestnut -- /Applications/Chestnut.app/Contents/Resources/chestnut-mcp/chestnut-mcp

It replaces an existing chestnut entry without asking. For OpenCode, use the Connect button.

OpenCode tabs an agent opens

When an agent, rather than you, opens an OpenCode tab in a folder that holds OpenCode project settings, the tab waits for your approval before it starts. Project settings are a .opencode folder or an opencode.jsonc or opencode.json file, in that folder or in any folder above it up to the top of the git repository. Outside a git repository, Chestnut checks every folder above it up to, but not including, your home folder, or up to the top of the disk for a folder outside your home folder. Chestnut asks you in its permission prompt, which names the project settings as the reason, and nothing starts until you choose Approve. A tab whose folder is cloned or created as it starts also waits for your approval, because Chestnut cannot check that folder first.

The reason is that OpenCode loads a repository's own settings and plugins when it starts, without asking. A repository you cloned could otherwise run its own code through a tab an agent opened, with no one looking. An OpenCode tab you open yourself never waits for this. A Codex tab never waits for this either, since Codex ignores a repository's own settings until you trust that folder in Codex.

Sessions started outside Chestnut

A session started outside Chestnut, in another terminal, has no card in the session list, so it cannot set a progress caption or list what it made beside its terminal. Sessions it opens start on Claude Code unless it asks for Codex or OpenCode by name, and they are not placed in a group or project. Searching, tidying and Quick Launch buttons work as they do inside Chestnut.

Knowing it worked

Start a fresh session in Terminal and ask it to rename itself. If the tab's title changes, the connection is live. For a session started in another terminal, ask it to list your recent Chestnut conversations instead.

If the session says it has no such tool, the agent has not picked up the registration. Run claude mcp list, codex mcp list or opencode mcp list in a terminal to check the chestnut entry is there, then start a new session. For Claude Code, restart Claude Code first.

Where to go next

Troubleshooting covers what to do when something does not behave as these pages describe.