Daintree Assistant

Overview

The Daintree Assistant is Claude Code or Codex, launched by Daintree in the assistant sidebar and pointed at Daintree itself rather than at your code. Ask it how a feature works and it searches the docs. Ask it to do something and it drives the app: it creates worktrees, launches agents, sends them prompts, waits for their answers and closes them when the work is done.

There is no separate engine and no Daintree account. The CLI runs on your own sign-in and your own plan, exactly as it does in an agent panel. What Daintree adds is the wiring: a session folder with the Assistant's instructions, a local MCP server that exposes a bounded tool set, a docs search server, and a runbook search server that gives it Daintree's step-by-step procedure for the task in front of it. Every tool call lands in a local audit log you can read, export and clear.

Opening the Assistant

Click the Daintree icon in the toolbar, or press Command-L ⌘L Control-L Ctrl+ L Control-L Ctrl+ L . The shortcut is a three-state toggle:

• Panel closed: opens the panel and focuses the input
• Panel open, focus elsewhere: moves focus into the input without closing anything
• Panel open and focused: closes the panel

Opening the panel does not start a session. Until you start one explicitly, no CLI is launched and no model request is made. After that first explicit start, opening the panel launches the agent for you.

Toolbar pips

When the panel is closed, the toolbar button carries a small status pip so you don't have to open it to know what's happening. Three signals compete for that one corner, in this order:

• MCP health (highest): amber and pulsing while the MCP server is starting, red if it failed to start (hover for the error). Nothing once it's ready
• Agent state: green while the agent is working or directing, amber while it's waiting. Suppressed while the panel is visible
• MCP anomaly (lowest): amber, raised when the audit log detects anomalous activity. The detail lives in the panel

The agent-state pip is read-aware: while the panel is open Daintree tracks the state you have already seen, so once you close it the pip only flags changes you haven't looked at.

Choosing Claude Code or Codex

The Assistant runs one of two CLIs: Claude Code or Codex. Both must be installed and signed in the way you would use them anywhere else. Only agents whose assistant wiring is marked stable appear in the picker. GitHub Copilot CLI is wired but experimental, so it is hidden.

First start

What the empty panel offers depends on what is installed:

• Both installed, nothing chosen yet: the panel asks Choose the agent that runs your assistant and lists each one with its mark. The one you pick is saved as your default and starts straight away.
• One installed, or a default already saved: a Start assistant button carrying that agent's mark. Before you have ever launched an agent, three starter questions sit under it; picking one starts the session and asks it.
• Neither installed: a pointer to settings.

Change the agent later under Settings > Daintree Assistant > Agent. The change applies to the next session, not the one already running.

Default models

Until you choose a model, Daintree launches each CLI with a recommended one, passed as --model:

Most of what the Assistant does is orchestration: short tool calls, status checks, relaying a prompt, reading a reply. That work rewards speed over depth. GPT-6 Luna is fast and inexpensive per token, so orchestration barely registers against a ChatGPT plan's Codex usage limits. It draws on the same quota as the rest of your Codex use; there is no separate allowance.

Pick a different model under Settings > Daintree Assistant > Agent > Model, or choose Default (CLI default) to launch without a --model flag and let the CLI decide. Switching agents resets the model to the new agent's recommendation. If the installed Codex is too old to offer GPT-6 Luna, the Assistant falls back to the CLI's own default rather than launching with a model the CLI can't serve. A --model in Custom CLI args overrides the picker.

It runs on your subscription

Daintree does not sit between the CLI and its provider. Claude Code uses your Claude sign-in or ANTHROPIC_API_KEY; Codex uses your ChatGPT sign-in or OPENAI_API_KEY. Usage counts against that plan or key exactly as it would in a terminal, and model traffic goes where it always goes for that CLI.

The panel

The Assistant opens as a push sidebar on the right: it pushes the panel grid over rather than floating on top of it, so your work stays visible while you talk to it. Drag the left edge to resize: the width runs from 320px to 800px, defaults to 380px, and is remembered across restarts. Once the resize handle has focus, arrow keys move it 10px at a time, Page Up and Page Down move 50px, and Home and End jump to the minimum and maximum. Escape closes the panel unless a terminal or editor inside it claims the key first.

Header

Parallel sessions

A project can keep up to three Assistant sessions. Use the + in the tab strip to add one, select a tab to return to its conversation, and use its close control to remove it. Switching tabs leaves background work running. Each tab has its own terminal, tool authorization, pinned worktree, figures, and resume ID. The tabs share a project session directory, so they are separate conversations, not separate filesystem sandboxes.

Arrow keys move focus between tabs; Enter or Space selects the focused tab. To clear the current conversation, use … > Restart conversation. This differs from adding another tab. Closing or restarting a conversation confirms when its current work or conversation needs protecting.

Footer

A single status row sits under the conversation. On the left is the tool-call activity strip and the turn-outcome pip. On the right is the pinned binding (the worktree and branch this session's tool calls resolve against), followed by the agent identity and, when one was set, the model.

The pinned binding matters because the Assistant's actions are anchored to the worktree the session was provisioned in, not to whatever you happen to be looking at. If you focus a different worktree, the binding turns amber and becomes a button that takes you back to the pinned one. Starting a new session is what re-pins it.

Talking to it

The Assistant uses the same input bar as your agent terminals: @file autocomplete, /commands, multi-line editing, Shift+Enter for a newline, Enter to send. The full feature set is in Unified Input. To dictate into the Assistant specifically, press Option-Shift-Command-V ⌥⇧⌘V Control-Alt-Shift-V Ctrl+ Alt+ Shift+ V Control-Alt-Shift-V Ctrl+ Alt+ Shift+ V . See Voice Input.

How-to questions are answered from the docs, with a link to every page it cites. Questions about what is running or stuck are answered from live state. When neither covers it, the Assistant says so and offers to search Daintree's GitHub issues or draft a new one. It never files an issue itself: it shows you the exact draft, and you file it.

Custom commands and skills

You can give the Assistant your own commands, skills, instructions and reference files without touching your agent configuration. Daintree reads ~/.daintree/assistant (global) and <project>/.daintree/assistant (per project, committable, and taking precedence). At each launch it copies what the selected CLI can use into the session's private folder: Claude Code gets commands and skills, Codex gets skills (invoked as $name), and both get instructions.md and the reference/ folder. Ordinary agent terminals never see this content. The next launch uses a project's folder without a separate approval step, so review changes to it like code.

Your global folder can also carry an mcp.json of extra MCP servers and a hooks.json of Claude Code hooks. Those run code, so they load only when you turn on Load my MCP servers and hooks, and a project's folder can never add them. Open the global folder from Settings > Daintree Assistant > Custom commands and skills. The layout, precedence rules, a worked example and sync-failure recovery are in Assistant Commands & Skills.

The three MCP servers

Daintree writes the Assistant's MCP configuration fresh for every session: a per-session config file for Claude Code, -c launch flags for Codex. Nothing in your own ~/.claude or ~/.codex configuration is touched. Up to three servers are wired, each behind its own setting:

All three are on by default. Turn one off and the next session starts without it, and the Assistant is told what that means: without daintree it can't see or change the app and says so, and without daintree-docs it says it can't check the docs rather than answering from memory. Tools from all three run without the CLI's own per-call approval prompt; the tool set and Daintree's confirmation dialogs are the gate for the local server, and the other two only read.

Runbooks

A runbook is Daintree's written procedure for a task: which tools to call, in what order, what to check between steps and when to stop and ask you. The Assistant's standing instructions carry only orientation and safety rules. The procedures live in a runbook catalog, and the Assistant looks up the relevant one before acting.

How it searches

• Before acting on a task, before its first call to daintree, it calls search_runbooks. A question about live state ("how much usage is left?", "why is it slow?") counts as a task. A how-to question does not: it is answered from the docs.
• One search per task. It doesn't search again for a step of the same task, a follow-up on it (closing its agents included), or a notice from an agent it launched.
• The query is one sentence of 8 to 15 words, saying what you want done the way you would type it. It keeps every part of the task and any condition on how ("…and start an agent on it", "…without fixing anything"), and leaves out specifics: numbers, branch, file, repo and people's names, pasted output and prompt text. It asks for at most three results.
• It follows the selected runbooks. Each result carries its full procedure. The Assistant follows the ones marked selected, plus the supporting runbooks they build on, and ignores the rest. When nothing is selected it carries on without mentioning it.
• If the search fails, it retries once, then proceeds and tells you the runbook couldn't be loaded.

What a search sends

The search is an ordinary MCP tool call from the CLI to assistant.daintree.org. Its arguments are the query sentence and the result limit. Daintree attaches no token or header to that connection, and nothing else from your session goes with it: no files, no terminal output, no conversation. The query itself is written by the model following the rule above, so keeping specifics out of it is an instruction the model follows rather than a filter Daintree applies. If you would rather no task summaries leave your machine at all, turn the setting off.

Turning it off

Settings > Daintree Assistant > Behavior > Follow runbooks is on by default. It depends on Daintree control, because runbooks are procedures for Daintree's own tools; with control off the toggle is disabled. Turning it off removes both the server and the search rule from the next session's instructions, so the Assistant works from its standing instructions alone.

Launching, prompting and closing agents

The core of the Assistant's job is running other agents for you. A handful of details make that dependable.

Batches

A round of work usually touches several agents at once, so each step has a batch form: agent.launchMany launches several agents with one shared prompt, terminal.sendCommandMany sends a separate prompt to each of several terminals, and terminal.closeMany closes several. Each item runs as its own single call, so the tool set, ownership rules, notices and audit log apply to every item exactly as they would one at a time. Results come back in order. A launch the Assistant makes gets a short readable terminal id such as claude-3f9a, which is cheaper to repeat and harder to transpose than a full UUID.

Closing moves a panel to the trash, where it stays briefly recoverable. The Assistant is instructed to confirm with you before closing several terminals.

Waiting for replies and notices

When the Assistant sends a prompt it can ask for a handback: Daintree appends an instruction asking the agent to print a done marker carrying a code. There are two ways to get the answer back:

• Wait for the reply (waitForReply): for answers due within minutes, such as a question or a vote. The call stays open until each agent prints its done marker, settles, exits or closes, and returns what each one said. The default wait is 5 minutes and the longest is 30.
• Notices (notify): for longer work. The Assistant ends its turn, and the moment an agent prints its done marker (or stops working, exits, or its panel closes) Daintree types a one-line notice into the Assistant's own prompt, quoting the agent's last screen lines. Claude Code and Codex both accept it mid-turn, so it doesn't wait for the Assistant to finish what it's doing.

Either way the reply arrives without the Assistant re-reading terminals or polling them. A new prompt or key press to the same terminal drops a notice that fired but hasn't been delivered yet, so a stale answer never reads as the answer to the new prompt. An Assistant waiting on notices is treated as busy, so hibernation won't shut it down and lose them.

A done marker proves the marker printed, not that the work is finished or correct. The agent's summary is treated as untrusted output, and the Assistant reports what it observed rather than what it concluded.

Answering an agent's dialogs

A CLI the Assistant launches can stop on its own dialog: a folder-trust prompt, a permission request, a login. The Assistant answers one only inside the authority you already gave it, and always tells you it did. Trusting the directory you asked it to launch in is inside that authority; anything else is handed to you by bringing that terminal into view. It picks an option by its label, and Daintree reads the screen and presses the keys, so it never guesses at y or a number. If it can't read the dialog, it doesn't answer it.

Images in answers

The Assistant can pin a documentation image into the panel with the help.displayImage tool, which is in the Core tool set. Figures land in a fixed-height thumbnail rail between the input bar and the footer, and clicking one opens it in a lightbox you can page through.

Three details make this behave predictably. Figure numbers are assigned by Daintree in sequence, never chosen by the agent, so an inline [image #2] reference in the reply always names the right thumbnail. Figures accumulate for the life of the session rather than being dismissed one at a time, so an older reference never goes dead. And the URL must be on daintree.org. data:, blob: and every other host are rejected, so the panel can't be used to render arbitrary remote content.

View full size: View full size

Watching what it does

Three signals in the panel tell you what the Assistant is doing to your workspace, without opening settings.

The activity strip in the footer is the live one. At rest it reads "Recent activity"; while a call runs it shows a spinner and the tool id, coalescing same-turn bursts as "2 calls · tool"; a settled call shows its result glyph and the tool id. The compact row omits durations; open the recent-calls popover or audit-log latency view for timing details. Successes decay back to the resting label after five seconds, errors do not: a failed call is worth keeping visible until the next call supersedes it. An in-flight row is withheld for the first 400ms so a fast call renders its result directly instead of flashing a spinner.

Clicking the strip opens the recent calls popover, which lists the last five calls for this session. It is deliberately short: a glance at what just happened, not an audit surface.

The turn-outcome pip sits beside it and appears only when the last turn classified as one of two failure shapes: Stopped early (the agent ended the turn without finishing) or Repeating steps (it kept redoing the same step). Both are a single amber dot with a short label, dismissed by clicking. Turn-outcome diagnostics are recorded separately from the audit log and are not affected by its retention setting.

For the full record, the audit log in Settings > Daintree Assistant > Privacy has a viewer, a latency table, copy-as-JSON, NDJSON export, and a clear button.

What it can do: tool sets

Everything the Assistant can do to Daintree goes through the local daintree server, and that server exposes one of two tool sets. The server filters its tool list to the set and rejects any call outside it, so the set is enforced by Daintree, not by the model's good behavior.

Some things are in neither set, so no Assistant session can reach them over MCP: git writes, forge writes (PRs, merges, issue edits), file reads and edits, UI navigation and layout, settings and theme writes, and bulk kills. The CLI has its own read tools for looking at a repository, and the rest is yours to drive from the UI. Core is the default because it covers what orchestration actually uses, and every tool in the set is re-sent to the model on each turn; a smaller list is cheaper and easier for the model to use well.

Seeing what a tool set allows

The disclosure pins the actions with the widest reach in a high blast radius group at the top of whichever set you are looking at. At Core that is worktree.deleteOwned; at Full it adds worktree.delete and worktree.resource.teardown. All three run project-defined teardown commands, which can destroy a remote resource. Below the tool set, a Live session card shows whether a session is connected, which set it is actually running, and whether that is above, below or equal to your configured default.

Confirmations

The tool set decides what is reachable. It does not remove confirmation: an action marked for confirmation, such as a worktree delete, still opens Daintree's own prompt even when the set allows it. Only your answer in Daintree approves it. If nobody answers in time the call fails with a timeout, and the Assistant is told that neither authorizes the action; it says it can't tell whether you declined or missed it, and offers to retry. It never works around an unanswered confirmation or a refusal through another tool.

When a tool is outside the tool set

If the Assistant calls a tool its session doesn't have, the call neither silently fails nor silently runs. A Tool not permitted banner names the tool and the set it needs, and offers:

• Allow this tool: grants repeat calls to that one tool for 15 minutes after its last use, with a 30-minute ceiling, without changing the set. While it is live, a banner shows the tool id and a countdown, with Revoke access beside it
• Set project default: saves the required set as this project's default for agent panes that connect to Daintree's MCP server, and raises this help session for 30 minutes of awake time. New help sessions still use the Tool set in settings
• Cancel: the call stops there

When a grant lapses, a neutral notice says so ("access expired" or "hit its 30-minute limit") and the next call asks again. A tool that is in neither set says so instead of offering anything. The Assistant itself is told not to retry or look for a way around the refusal, and to tell you which set the tool needs.

For longer automation there are automation grants, issued from the Live session card: list the tool ids to approve and a maximum number of uses, and the session can call them without a per-call prompt, including actions that would otherwise ask for confirmation. Live grants show their tools, remaining uses and time left, each with a Revoke button, and the whole lifecycle (issue, use, exhaust, expire, revoke) is mirrored into the audit log.

Claude Code and Codex are locked down differently

The tool set binds only the daintree server. Each CLI also has its own local tools, and the two CLIs restrain them differently:

• Claude Code is locked down at its tool layer. The session's settings allow reading files, web fetches and the forge CLIs (gh, glab, tea) for searching issues and PRs, and deny every file edit and the forge write commands (creating issues, PRs and repositories, merging PRs, deleting repositories). A Claude Code deny is a hard block, not a prompt.
• Codex gets no bundled deny list, and its session folder is writable by design. Daintree adds no sandbox or approval-policy flag, so Codex runs under your own Codex settings. Its instructions say the shell and gh are for reading, and that the rule is instruction rather than enforcement. For Codex, the daintree tool set is the enforcement point.

Both are told never to use the shell, a forge CLI or gh api to do what a Daintree tool does, or what the tool set or a confirmation refused.

Settings

Everything lives under Settings > Daintree Assistant. Changes apply to new sessions, not the one currently running.

Agent

Agent picks the CLI: Claude or Codex. Model appears below it with that agent's models; the recommended one is selected until you choose another, and Default (CLI default) launches without a --model flag. If a previously chosen agent is removed or loses assistant support, a notice says so and asks you to pick another. If the installed CLI is older than the Assistant needs, a notice names the required and installed versions with a link to agent settings.

Behavior

• Search documentation (on by default): connects the daintree-docs server so the Assistant can search Daintree's docs and changelog while answering
• Daintree control (on by default): connects the local daintree server so it can call Daintree actions. Enabling it starts a local HTTP server on 127.0.0.1, and the server's status shows underneath
• Follow runbooks (on by default, needs Daintree control): connects daintree-runbooks and adds the search rule to the Assistant's instructions

Security

Tool set chooses Core (default) or Full. Below it sits the CLI's permission bypass switch, off by default and shown only for a CLI that has one, then the What this tool set allows disclosure and the Live session card with its per-tool and automation grants.

Privacy

Capture audit log turns recording on or off. Audit log retention sets how long records are kept locally: 7 days (default), 30 days, or Off. An Advanced diagnostics disclosure holds the audit-log viewer, the latency table, turn-outcome diagnostics, and, if an external client has been connecting with a stale or missing key, a count of rejected requests. External MCP traffic is filtered out of this view; it belongs to the MCP server tab.

Launch options

Custom CLI args appends whitespace-separated flags to the launch command; a --model here overrides the model picker. Hibernate after sets how long the panel can sit hidden before the Assistant shuts down and releases memory: Off, 5 minutes (default), 15 minutes, 30 minutes, 1 hour, or 2 hours. Reopening resumes the same conversation. Off keeps it resident until you close it.

Custom commands and skills

Assistant folder opens ~/.daintree/assistant, creating it if needed. Load my MCP servers and hooks (off by default) starts the servers in that folder's mcp.json and runs the Claude Code hooks in its hooks.json. See Custom commands and skills.

External clients

Shares the Assistant's local MCP server with other clients, such as Claude Code or Cursor running outside Daintree. While the server is running, Copy MCP config copies a ready-to-paste client configuration for its port, and Rotate MCP key… issues a new API key after a confirmation, disconnecting every client that holds the old one. External clients connect at their own separately budgeted tier, not at the Assistant's tool set. The MCP server settings tab also lists Daintree's own internal connections (the help sessions themselves, with their session and request counts), so the Assistant's traffic is legible next to any external clients.

Sessions, hibernation and resume

Starting a session runs a short state machine, and the panel names the phase it is in rather than showing an undifferentiated spinner: Checking version…, Preparing session…, Starting assistant…, and Saving session… on the way out. A Cancel affordance appears if it runs long.

When a launch fails, the panel says why in plain terms and offers the recovery that fits: Retry plus Open settings when the assistant services didn't start or respond, Retry plus Open logs when the project's commands and skills couldn't be refreshed, Retry alone when the agent didn't start, and Open logs plus the installer page when Daintree's bundled assistant files are missing (retrying that one cannot help). If the chosen CLI isn't installed at all, a gate offers to open agent settings, or to run anyway.

If the installed CLI is older than the Assistant requires, a version gate blocks the launch, names the required and installed versions, and offers Check again so you can update the CLI without restarting Daintree. Claude Code needs 1.0.0 or later; Codex has no minimum.

When the panel stays hidden past the hibernation timer and the agent is idle, Daintree shuts the agent down cleanly and captures its resume token. Reopen the panel and the conversation comes back with a banner confirming it resumed. If the agent is busy, or is waiting on notices from agents it launched, Daintree rechecks periodically rather than killing work in progress. Resume is keyed to the project and session tab, and each tab needs its own explicit resume ID: using "latest in this folder" could resume a sibling tab's conversation. Resume only fires when the next launch targets the same agent, so switching agents never grafts one conversation onto another.

A session lost to memory eviction or a renderer crash is offered back as Resume assistant instead of a cold start. The Assistant also gets a private scratch directory for throwaway files, so it doesn't litter your repo, and when you ask it can tell you where its own session transcript is on disk. For the broader mechanics, see Session Management.

Privacy and trust

The Assistant is Claude Code or Codex, authenticated with your existing CLI configuration. Your conversation goes to Anthropic or OpenAI exactly as it would from a terminal, on your plan or key. Daintree adds no model endpoint and holds no provider credentials.

Two kinds of request go from the CLI to a Daintree-operated endpoint, each behind a setting you can turn off:

• Docs searches go to daintree.org/api/mcp while Search documentation is on.
• Runbook searches go to assistant.daintree.org while Follow runbooks is on. Each one carries a single task sentence and a result limit, and nothing from your files, terminals or conversation. See What a search sends.

The daintree server that drives the app is local, on 127.0.0.1, behind a bearer token minted per session.

Every tool it dispatches through daintree is recorded in a local audit log you can read, export and clear. The Core tool set can delete worktrees the session created, with your confirmation; Full can delete any eligible worktree and tear down its resources, also with confirmation. The tool set is a Daintree boundary, not a sandbox for Claude Code's or Codex's own shell and file tools; see how each is locked down. For the broader picture on sandboxing and data storage, see Security & Privacy.

Troubleshooting

Implementation reference

For exact membership of each tool set, inspect the tool set allowlists. The runbook wiring holds the endpoint and the search rule the Assistant is given, and the help workspace README covers the prompts, the permission lockdown and the three MCP servers. The session-slot contract explains the three-session limit, shared directory, and separate resume identities.