Getting started

Chestnut is a desktop app that organizes your Claude Code, Codex and OpenCode sessions in one window and keeps every conversation they produce searchable on your own machine. It runs on Apple Silicon Macs with macOS 13 or later.

Install

Download Chestnut from the download page. It asks one question first: whether you use Chestnut personally or for professional work. Chestnut is free for personal use: your own projects, learning, hobby work and unpaid open source. Paid or business work needs Chestnut Pro, at $10 per user per month or $96 a year, which starts with a 30-day free trial on your first Pro subscription.

If the download page says Chestnut is in private preview instead, create a free account there and we'll email you when your access is ready. Then sign in and download the app from the download page or from your account page.

Either way, drag the app to Applications and open it. macOS may ask you to confirm the first launch of a newly downloaded app. The installed app runs without an account; see Signing in below.

Chestnut runs a process in the background alongside the window. Your conversation history stays on your machine, in a database there. For automatic updates, the app sends basic technical details with its update checks and, once you agree to the privacy policy, a random install ID that names no account. Conversation text leaves your machine only when your own coding agent writes a summary or Notebook entry, with your permission, or when you choose to attach logs to a private report. Crash reports stay off unless you turn them on, during setup or later in Settings > Privacy; they never include your conversations, prompts or file paths.

First run

The first launch walks through six steps, shown as bars at the top of the window:

1. Welcome. What the app does.
2. Agents. Chestnut checks for Claude Code, Codex and OpenCode, and shows each one as Ready, installed but not signed in, or not installed. Any one Ready agent is enough to carry on. If none is, the row tells you what to do: install the agent, or run its sign-in command in a terminal (for OpenCode, also set a default model in its own opencode.json and install git, which its background tasks need; until then its row reads Installed, needs setup with the reason under it), then choose Check again. Every Ready agent is turned on for new sessions.
3. Making your conversations searchable. Chestnut reads the Claude Code, Codex and OpenCode conversations already on your machine and builds a local search index from them. Nothing is uploaded. When it finishes, it shows how many conversations it found for each agent.
4. Connect your agents. Every session you start in Chestnut runs your own agent, and Chestnut can add three things to it: a short note in its instructions, Chestnut's tools, and (for Claude Code) a help plugin. They let the agent keep its session card up to date, search your past sessions, and start or organize other sessions, and they use a little of that agent's plan. The screen has a switch for each agent Chestnut found, each on, and See exactly what we add shows the note's full text and what each addition costs. A switched-off agent runs in Chestnut as it does anywhere else. You can change this later in Settings > Agent integration.
5. Automations. Chestnut explains the work it can do by itself, automatic summaries and a daily Notebook entry, and asks whether it may. Each of those runs a real session on one of your agents and uses that agent's plan. With one Ready agent, the screen names it; with two or more, you pick one, and the one you used most recently is already selected. The same screen asks whether to send crash reports. When Claude Code is the agent, the last line above Continue says Chestnut lets Claude work in its own folder and shows its path: Chestnut trusts that one folder for Claude before each background run, so Claude never stops to ask. If you set up before this line existed, Chestnut shows this screen once more on its next launch, and background work on Claude waits until you press Continue.
6. Sign in, or continue without an account. Covered below.

The scan is why the app has something to show you before you have run a single session inside it. If you have used any of these agents before, your existing conversations appear in Conversations once scanning finishes.

On the Automations screen, if you leave summaries or the Notebook on, Continue first sends that agent one small prompt to make sure it answers. While it waits, Cancel stops it and records nothing. If the prompt fails, the screen shows the agent's own error, and you can choose Try again, or pick another agent if more than one is Ready. With both turned off, nothing is sent. You can change any of this later in Settings.

Signing in

The free app works fully without an account. After setup, the sign-in screen appears once: choose Continue without an account to go straight to the app on the Free plan, or Sign in with your browser, which opens sign-in in your normal browser and picks the session back up when you return. Chestnut remembers the choice and does not ask again. You can sign in later from Settings > Account. Your conversations never leave your Mac either way.

An account is needed only for Chestnut Pro, for test builds (Settings > About > Sign in to get test builds) and for sending feedback privately. Signing out, from Settings > Account, keeps the app open on the Free plan with your history in place.

If you do not have an account yet, choose Create an account. You enter your email address, agree to the terms and licence, and choose Send me the link. Opening that link is where you choose your password, and it is the point at which the account is created, so nothing exists under your address until you do. The link works once and expires after a day; if yours has expired, choose Resend signup link on the sign-in page.

You can also choose Continue with Google instead, which needs no password at all. If you already have an account on that same address, the Google button takes you to it rather than starting a second one, so your plan comes with you whichever button you press.

An account is what carries a Pro plan. The Free plan, signed in or not, gets the whole app, with no feature limits. Chestnut Pro is the licence for paid or business work, at $10 per user per month or $96 a year after a 30-day free trial on your first Pro subscription, and adds early access to beta builds and email support.

On Pro, Settings > Account > Manage subscription opens your account page on the website, where you change your payment method, see invoices or cancel. If a payment fails, the same panel says so and links to the fix.

Finding your way around

The rail down the left edge is how you move between panels. Each item shows its icon with its name underneath, and the rail stays the same width all the time. It holds two groups, with two round buttons at the bottom.

App holds the panels about Chestnut itself:

• News shows release notes and feature posts, fetched from the website, so it is the fastest way to see what changed in a version you just installed. Chestnut opens on News the first time, and after that on whichever item you had open last.
• Status shows what Chestnut has been doing (conversation counts, how background tasks are going, anything stuck) and, under System & Diagnostics, the version, database and log locations, and the repair tools described in Troubleshooting.
• Tasks lists background work the app is doing on your behalf.

Workspace holds the panels about your work:

• Terminal runs Claude Code, Codex and OpenCode sessions in tabs.
• Conversations is your searchable history.
• Notebook is a daily journal of what you worked on.
• Projects groups sessions and conversations by directory.
• Actions lists fixes Chestnut suggests for friction it finds in your conversations.
• Prompts shows what Chestnut tells the AI for each feature, in the order it is sent. You can change the wording or restore the default.

Help and settings are the two round buttons at the bottom of the rail:

• Help opens these pages inside the app. They are part of Chestnut itself, so they read with the network off and while the app is reconnecting. A Send feedback button under the page list reports a problem without leaving the app, publicly on GitHub or privately to us when you are signed in.
• Settings holds configuration, including the command line arguments, terminal font and theme described in the pages that follow, your account, and Backup & storage for keeping a copy of your history.

Before the rail appears (during setup, on the sign-in screen, and while the app is reconnecting) a round Help button in the corner of the window opens the same panel.

The bar along the bottom of the window shows a usage chip for each agent you used in the last 7 days and whether new conversations are being imported. The top of the window shows your plan and Chestnut version, and offers an update when one is ready. The search field at the top searches everything; see Conversations and search.

Where to go next

If you want to start working immediately, read Terminal and projects.

If you came to Chestnut mainly to search history you already have, read Conversations and search.