Terminal and projects

Terminal

Terminal runs Claude Code, Codex and OpenCode sessions inside Chestnut, in tabs. A session is the real claude, codex, or opencode process with a real terminal attached, so anything you would do in a terminal works here.

Running sessions inside the app rather than in a separate terminal is what lets Chestnut record them. A session you start elsewhere still gets imported, but only the ones Chestnut starts get the extras below.

Starting a session

The New session button at the top of the list on the left of Terminal asks where the session runs: one of your projects, another folder (Open elsewhere…), or your home folder. It then takes an optional Session name, Initial prompt and Model. Cmd+Enter in the prompt launches it.

Quick Launch, beside it, holds saved buttons that each start a prepared session in one click, with its own folder, prompt and model. Add or change them from Manage Quick Launch….

When you restart Chestnut, your tabs come back. If many were open, a Reopen sessions chooser asks which to start again; the rest come back as cards you can start later.

The session list

Each session has a card in the list on the left of Terminal, showing its title, what it is doing, and a status such as working, Needs permission or idle. The User and App tabs at the bottom separate your sessions from the ones Chestnut runs for itself.

You can arrange the list yourself: drag cards to reorder them, put sessions into named groups with New group, collapse a group to see just its members' status, and give a card or a group a colour from its menu. Organize with AI (the sparkles button) proposes an arrangement and changes nothing until you apply it. Cmd+Shift+T reopens a tab you closed.

The Inspector

Each tab has an Inspector beside its terminal, shown or hidden with the button in the tab's header. It shows what the session has produced and found: its artifacts, timeline, top friction items, pull requests with their state and checks, and references such as tickets. Set your Linear workspace in Settings > Links so ticket keys there open in Linear.

Rate limits

When a session stops on a temporary rate limit or server error, Chestnut waits and types continue for you, with a countdown in the tab's header. If it keeps failing, or the agent reports that you have hit your usage cap, the session is parked instead; for a usage cap, the header shows when it resets.

Pasting images and dropping files

With an image on the clipboard, for example a macOS screenshot, press Cmd+V in a session tab. Chestnut saves the image to a file and pastes its path, which Claude Code turns into an image attachment; in a Codex or OpenCode tab, what happens to that path is up to the agent. Dragging an image file from Finder does the same thing. Dropping any other file on a tab pastes its path.

Copies made by programs in a tab

A program in a session, such as vim, tmux or the agent itself, can put text on your clipboard. Chestnut allows that only from the tab you are looking at, while Chestnut is the app in front. A copy made from a background tab, while another view such as Settings is open, or while you are in another app is dropped, so run it again from the tab once you are back.

Usage

The bar along the bottom of the window shows a usage chip for each agent that ran on your Mac in the last 7 days. For Claude Code and Codex it shows how much of your plan's limits you have used; OpenCode's says it has no plan limit. Click one for details. The same bar shows whether Chestnut is importing new conversations.

Codex and OpenCode

Claude Code is ready as soon as Chestnut finds the claude command. Codex and OpenCode are switched on too, so an agent you install later shows up in the new-session dialog with nothing to change in Settings.

Settings for each agent

Settings > CLI backends has a card for Codex and one for OpenCode:

• An agent that is not installed is left out of the new-session dialog, and its card says why, for example that its command was not found on your PATH.
• You can switch either one off, and it stays off until you switch it back on, through updates too. An agent you switched off that is installed and signed in is marked Detected.
• Each has a command field, so a binary that is not on your PATH still works, an Extra arguments field, and an Environment variables field for that agent alone.
• A warning shows under Codex or OpenCode if the installed version is one Chestnut has not been tested with, or if its version cannot be read. You can still use Codex. OpenCode will not launch if its version cannot be read or its major version is not 1 or 2; the error names the versions Chestnut supports.

OpenCode

OpenCode runs on your own OpenCode configuration and login, so it answers on the default model your opencode.json names. To use LM Studio or any other local model, configure it in OpenCode's own opencode.json; Chestnut has no provider settings for it.

With OpenCode 2, an OpenCode tab in Chestnut keeps its own list of open sessions and its own prompt history, so it never shows your other OpenCode sessions or prompts. It starts on OpenCode's default theme, display settings and recent models.

If OpenCode is on but cannot run background tasks, for example because git is missing, the reason shows under its switch, and its terminal tabs still work.

Codex

A Codex tab runs only the hooks Chestnut sets up. Hooks in your own ~/.codex that you have not reviewed in Codex do not run there, and the tab shows Needs permission while Codex's hooks review screen is open.

A Codex tab also ignores a repository's own .codex settings: MCP servers it defines, its hooks, and any sandbox or approval setting it carries, unless you have trusted that folder in Codex yourself. In a folder you have not trusted, Codex asks before running any command it does not know to be safe. To get Codex's usual approvals and the repository's own MCP servers, open a terminal in the repository's top folder, run codex, and answer Yes to its trust question. Chestnut then follows your answer for tabs opened in that folder.

With Codex 0.160.0 or later, a tab in a folder you have not trusted first shows Codex's Folder access screen, and the tab shows Needs permission until you answer it. Press Enter to open the folder restricted. Background Codex work never sees this screen: it runs in a folder Chestnut creates for it.

Choosing the agent for a tab

When Codex or OpenCode is installed and switched on, the new-session dialog has a Backend row: pick Claude Code, Codex or OpenCode for that tab. The Model you enter there reaches every agent; OpenCode takes it written provider/model, for example openrouter/openai/gpt-4o-mini. An agent that cannot start, for example because its command is missing, is left out of the row; Settings > CLI backends says why. Codex and OpenCode sessions are recorded, searchable, and resumable the same way Claude Code sessions are.

Helper agents

When a Codex, OpenCode or Claude session hands work to helper agents (Codex subagents, OpenCode's task tool, Claude's background helpers), the session's card shows a small robot badge with the number of helpers, and a pulsing dot while any is still running. Click the badge to see each helper's name and whether it is running or finished, and click a helper to read its own transcript in Conversations. These rows are read-only: you cannot type into a helper, stop it or move it to a group. Helpers' text is searchable like any other session's.

A Claude session that leads an agent team shows its teammates on the same badge: one small square per teammate, coloured by that teammate's status, after a divider when the session also has helpers. The badge turns amber while a teammate is waiting on you. Click it to see the teammates above the helpers; click a teammate to open its terminal, or use its menu to reload or close it. Teammates have no card of their own and no ⌘ number, so ⌘1 to ⌘9 and ⌘↑/⌘↓ skip them. If a team's lead is not open, the team shows as one Agent team card marked "Lead closed"; click it to reach the teammates.

A few details:

• A helper that stopped because its tab closed, crashed or Chestnut restarted shows finished. For a Claude helper this follows its session's exit; if the session was force-quit, the helper keeps showing running.
• A Claude helper that its session did not start in the background, or that another helper started, has no row of its own; its text stays in the session's transcript.
• A helper started during a new Codex or OpenCode tab's first turn appears when that turn ends.

Projects

Projects groups your work by directory. A project is a directory Chestnut knows about, plus the settings you attach to it. If you have none yet, Suggest from history groups your past conversations into projects for you to review.

Projects matter for three reasons:

• Conversations and sessions are associated with the project whose directory they ran in, so you can filter your history down to one codebase.
• A project's page is a place to start work: launch a session, see what is Running now and your Recent sessions, and see the checkouts on disk.
• A project carries its own launch settings: how a session gets its copy of the code (In-Place, Stash & Branch, Fresh Checkout or Choose Instance; a Worktree can be picked for a single launch), Prep commands to run first, and its own arguments for each agent, described below.

A project's coloured name or badge, wherever it appears (a session tab's header, a conversation's header and Inspector, the action dialog, an action type's Scope, a prompt's details), opens that project's page when you click it or press Enter on it.

Arguments every session starts with

Settings > Launch defaults has a Default Claude CLI args field. Whatever you put there is appended to every claude launch Chestnut makes: tabs you open yourself, sessions started from a conversation, and sessions started from an action. Codex and OpenCode have their own Extra arguments in Settings > CLI backends.

Arguments are split using ordinary shell rules, so --system-prompt "be terse" stays a single argument with its space intact.

A project's CLI arguments (one field each for Claude Code, Codex and OpenCode) replace that agent's global arguments for launches in the project rather than adding to them. That is worth knowing before you wonder why a global argument stopped applying in one repository.

Environment variables for sessions

Settings > Launch defaults also has an Environment variables field taking one NAME=value per line. Those are applied to every Claude session Chestnut starts (Codex and OpenCode each have their own field under Settings > CLI backends, and never receive Claude's). That is how you set a proxy or point Claude at a different model provider without launching Chestnut from a specially prepared shell.

Two things to know before putting anything sensitive there:

• Values are stored as plain text in Chestnut's config file. Chestnut logs the names it applied but never the values.
• A few variable names Chestnut sets itself are refused rather than quietly ignored. The session fails to start and names the variable it rejected, so a setting that could never have worked does not sit there looking like it did.

Terminal appearance

Settings > Terminal sets the font and font size every session tab renders in. The family picker lists monospace families detected on your machine and deliberately excludes fonts that cannot render terminal text properly. You can type a family name the detector missed and press Enter to use it. System default goes back to the font Chestnut ships with.

If Chestnut cannot read your installed fonts at all, the picker lists nothing and tells you why rather than showing a plausible-looking list. Reopening Settings retries a failed detection.

Settings > Appearance picks a Light, Dark or System theme for the whole app.

Where to go next

Conversations and search covers what happens to a session after you finish it.