AI Agents

Built-in Agents

Daintree supports seven AI coding agents out of the box. Each one runs as a CLI process in a dedicated terminal panel with full PTY emulation.

All keyboard shortcuts can be rebound in Keyboard Shortcuts. Kiro CLI runs on macOS and Linux only; every other agent works on all three platforms.

Installing Agents

Each built-in agent is an independent CLI tool that you install yourself. Daintree doesn't bundle the agent binaries, it just launches and tracks them. Once an agent is installed and authenticated, Daintree picks it up automatically and pins it to the toolbar.

For the install and authentication status of every agent on your system, open Settings > CLI Agents. The same panel also links directly to each agent's install docs.

Kiro CLI

Kiro is Amazon's spec-driven coding agent. Install it with the official script:

curl -fsSL https://cli.kiro.dev/install | bash

curl -fsSL https://cli.kiro.dev/install | bash

GitHub Copilot CLI

Install GitHub Copilot CLI from npm. The same command works on macOS, Windows, and Linux:

npm install -g @github/copilot

After installing, run copilot login to authenticate. Copilot uses GitHub's OAuth device flow: the CLI prints an 8-character code, opens github.com/login/device in your browser, and you paste the code to authorize the session. The token is stored in your OS keychain (with a fallback to ~/.copilot/config.json for headless Linux and CI environments).

Copilot CLI supports 13 models out of the box (Claude Sonnet, Opus, and Haiku; GPT-5.x; Gemini 2.5/3 Pro) and has a 160,000-token context window. Switch models mid-session with /model, or start the CLI pinned to one with copilot --model <name>.

Launching an Agent

There are a few ways to launch an agent:

• Keyboard shortcut — press the agent's shortcut from the table above to launch it directly.
• Toolbar button — click the agent icon in the toolbar.
• Worktree card — use the agent launch buttons on any worktree card in the sidebar.
• Panel palette — open with Cmd/Ctrl+N and select the agent type.

The agent launches in the active worktree's directory, so it picks up the right branch and working tree straight away.

Agents that are installed but not pinned to the toolbar live in the Agent Tray, a dropdown next to the toolbar agent buttons. Agents that need authentication show up there too so you always have a path to finish setting them up.

Agent Tray

With seven built-in agents plus any custom ones you've added, pinning every agent to the toolbar gets crowded fast. The Agent Tray keeps the toolbar clean: Daintree only pins agents it has confirmed are installed and ready, and the rest live one click away in the tray.

The tray is the plug icon in the toolbar, next to the agent buttons. It appears whenever there are installed agents that aren't pinned, or agents that need setup. If every built-in agent is pinned and fully authenticated, the tray button hides itself.

Launch Section

The Launch section lists installed agents that aren't currently pinned to the toolbar. Each row shows the agent icon, a running indicator if a session is already active, and a pin toggle. Click a row to launch the agent in the active worktree. Press P while a row is focused to pin it to the toolbar instead.

Rows are sorted by recent use in the Panel Palette, so the agent you've been reaching for most sits at the top.

Needs Setup Section

The Needs Setup section collects agents whose CLI is installed but where Daintree hasn't detected an authenticated session. Each row shows a greyed-out icon with an amber "Needs login" badge. Clicking a row opens Settings > CLI Agents scrolled to that agent so you can finish signing in.

The Kiro false-negative from the install section applies here too. If Kiro is signed in via AWS Builder ID or a social provider, it will sit in Needs Setup permanently even though it works fine.

Discovery Badge

When Daintree detects a newly installed agent that it hasn't seen before, a small blue dot appears on the tray button. The dot clears the first time you open the tray, so you can tell at a glance when a freshly installed CLI has been picked up.

Pinning

Pinning and install state are tracked separately. Daintree automatically pins an agent the first time it confirms the agent is installed and ready, so new installs show up in the toolbar without any configuration. If an agent was installed before this detection pass (for example, you installed it in another terminal after Daintree already checked) and it doesn't appear in the toolbar, open the tray and either launch it from the Launch section or pin it manually with the pin icon (or P). Unpinning works the same way, and unpinned agents stay available in the tray so you can still launch them on demand.

The tray footer has "Manage Agents…" (opens Settings > CLI Agents) and "Customize Toolbar…" (opens the toolbar customization panel) for anything the inline pin toggle doesn't cover.

Session Resume

When you close an agent panel, let its trash window expire, or quit Daintree, the app captures the agent's session ID from its terminal output. This lets you pick up exactly where you left off instead of starting a fresh conversation.

To resume a session, open the Panel Palette (Cmd/Ctrl+N) and scroll to the Resume Sessions section at the bottom. Each entry shows the agent name, model, and how long ago the session ran (e.g. "Sonnet · 2h ago"). Selecting one re-launches the agent with the correct resume flag.

Daintree handles the resume syntax automatically. Under the hood, it passes the session ID using each agent's CLI flag:

Daintree stores up to 50 sessions per worktree and prunes anything older than 30 days. Sessions are scoped to the directory they were started in. Any launch flags you used originally (like --dangerously-skip-permissions for Claude) are preserved on resume.

For the full mechanics (the 20-second trash window, what gets saved, and what happens when a worktree is deleted), see Agent Session History.

Pre-Agent Snapshots

Every time an agent starts working, Daintree captures a snapshot of your working tree automatically. If you had uncommitted changes or untracked files before the agent ran, this gives you a one-click restore point to get back to that exact state. No setup, no configuration. It just happens in the background.

Under the hood, Daintree runs git stash push --include-untracked to capture all uncommitted changes and untracked files, then immediately re-applies the stash so the agent has the full working tree to operate on. The stash entry stays in place as your restore point while the agent works.

One snapshot is stored per worktree. If an agent finishes and you start a second agent on the same worktree without reverting, the original snapshot is preserved. Subsequent agent starts will not overwrite an existing restore point.

Reverting Agent Changes

To roll back to the pre-agent state, open the worktree card context menu (the ... button) and select Revert Agent Changes. This discards all uncommitted changes in the working tree, including any edits you made after the agent ran, and restores exactly the state that was captured at snapshot time. The whole operation takes a single click.

The menu item only appears on worktrees that have an active snapshot with uncommitted changes. Once you revert successfully, the menu item disappears and the snapshot is consumed. If your working tree was clean when the agent started (no uncommitted changes), there is nothing to restore, so the revert option will not appear.

For a more granular review of what an agent changed before deciding whether to revert, check the Review Hub. You can inspect individual file diffs and stage changes selectively rather than reverting everything.

Edge Cases

• Conflicted files at agent start — if the working tree has unresolved merge conflicts when the agent launches, the snapshot is skipped. No menu item appears.
• Conflicts after revert — if applying the snapshot produces merge conflicts, Daintree completes the revert but shows a warning that conflicts need manual resolution.
• Stash deleted manually — if the underlying git stash entry was removed before reverting (via git stash drop or similar), the revert fails and Daintree shows an error notification.
• Snapshot expiry — snapshots are automatically pruned after 48 hours. The stash entry is also dropped at that point.

Help Agent

Daintree includes a built-in documentation assistant called the Help Agent. It spawns a real CLI agent session (Claude Code, Gemini CLI, or Codex CLI) inside a dedicated help/ workspace bundled with the app. The agent is locked to read-only, help-assistant mode and connects to Daintree's live documentation through the daintree-docs MCP server. Think of it as a knowledgeable guide that can search the docs, answer questions about features and settings, and even draft GitHub issues on your behalf.

Opening the Help Agent

There are four ways to open the Help Agent:

• Keyboard shortcut — Cmd+Shift+H (macOS) or Ctrl+Shift+H (Windows/Linux)
• Dock button — click the Daintree icon in the dock (the tab bar at the bottom of each panel)
• App menu — Help > "Launch Help Agent"
• Action palette — open with Cmd+Shift+P and search for "Launch Help Agent"

The Help Agent opens as a resizable overlay panel on the right side of the window, separate from the Portal. Click outside the panel or press the close button to dismiss it.

Agent Picker

The first time you open the Help Agent, a picker lists the available agents: Claude Code, Gemini CLI, and Codex CLI. Select one to start your session. Daintree remembers your choice, so subsequent opens skip the picker and launch your preferred agent automatically.

To switch agents, click the back arrow (←) in the panel header. This returns you to the picker and clears the current preference.

You can also set a persistent default in Settings > CLI Agents under the "Default agent" option. When a default is set, the Help Agent always launches with that agent without showing the picker. If no default is configured, Daintree uses the first installed agent it finds (Claude → Gemini → Codex).

Panel Layout and Resizing

The help panel defaults to 380 pixels wide, with a minimum of 320px and a maximum of 800px. Drag the left edge to resize it. Keyboard users can focus the resize handle and use ArrowLeft / ArrowRight to adjust in 10-pixel steps. Your width preference persists between sessions.

Each time you open the panel, it starts a fresh conversation. Closing the panel clears the session entirely, and help sessions don't appear as tabs in the dock.

What the Help Agent Can Do

The Help Agent searches Daintree's documentation in real time through the daintree-docs MCP server. It can:

• Answer questions about Daintree features, settings, and workflows
• Search the documentation and surface relevant pages
• Share links to YouTube tutorial videos found in the docs
• Search existing GitHub issues related to your question
• Draft new GitHub issues on Daintree's repository for feature requests or bugs (with your approval)

The agent operates read-only. It cannot edit files, run shell commands, or help with your own project's codebase. It's strictly a Daintree documentation assistant.

Agent Availability

Each agent has one of four availability states. Daintree uses a layered detection process: first your PATH, then known installer paths, then an npx probe for npm-distributed CLIs. It then looks for an authentication credential so it can tell installed-but-not-signed-in apart from installed-and-ready.

For a full per-agent breakdown, open Settings > CLI Agents. The panel reports which detection step succeeded, the path Daintree is launching from, and what it looked for when determining authentication status.

Agent State Tracking

Daintree monitors each agent's terminal output in real time and tracks its state. States show up as badges on the worktree card and terminal panel:

State detection works by pattern-matching terminal output. Each agent has its own set of patterns for identifying prompts, streaming indicators, tool execution, and approval requests. The patterns are tuned per agent, so detection stays accurate across different CLI output formats.

CPU-Based Idle Detection

Sometimes an agent launches a long-running process like a compiler or test suite that produces no terminal output for a while. Rather than flickering to "idle" prematurely, Daintree monitors the process tree's CPU usage. If any child process is still active, the agent stays in its current state until the work actually finishes. This is transparent to you as a user: builds and test runs just show the correct state without false idle transitions.

Activity Headlines

Beyond the state badge, each agent panel shows an activity headline, a short description of what the agent is doing right now (e.g. "Editing src/index.ts" or "Running tests"). These are generated from terminal output in real time.

State Chip Tooltip

Each agent panel header displays a small circular state chip, separate from the state badge shown on worktree cards in the sidebar. The chip's icon and color reflect the agent's current state:

The chip is hidden when the agent is idle. It also hides for the completed state if no session cost data is available.

If there are errors captured from agent terminal output, a small red dot appears at the top-right corner of the chip. The dot clears once the errors are dismissed from the panel.

When a session completes and cost data is available, the chip shows the session cost and token count as inline text next to the icon (e.g. $1.23 · 45k). This is the only case where session data appears outside the tooltip.

Tooltip Fields

Hovering the state chip opens a tooltip with live session metadata. All fields are conditional and only appear when their data is available:

The duration text within the State details field only appears for the working, waiting, and directing states, and only after the agent has been in that state for at least 10 seconds. This prevents a brief 0s flash when a state has barely started.

The change trigger tells you what caused the last state transition. Possible values are: Input, Output, Heuristic, AI classification, Timeout, Exit, Activity, and Title. High-confidence triggers like Input and Output always show 100% confidence (so no percentage is displayed). Lower-confidence triggers like Heuristic or AI classification show their confidence score explicitly.

Both the session elapsed time and the state duration update every 30 seconds, not in real time. A freshly opened tooltip may show a slightly stale value that catches up on the next refresh cycle.

Notifications

When agents enter the waiting state, Daintree notifies you via title bar and dock badges. For the full notification and sound system, see Notifications & Sound.

The two main notification channels:

• Title bar badge — shows the count of agents needing attention, e.g. "(2) Daintree"
• macOS dock badge — same count on the dock icon

Notifications clear automatically when you focus the Daintree window.

Quit Confirmation

When you quit Daintree while any agent panel is in the Working or Running state, Daintree intercepts the quit and shows a confirmation dialog automatically. The check runs on every quit attempt — via Cmd+Q on macOS, Alt+F4 on Windows, or File > Quit on any platform.

The dialog is titled "Agents are working" and reports how many agents are currently active. Two choices are presented: Cancel (the default, keyboard-highlighted) dismisses the dialog and leaves everything running; Quit Anyway proceeds with a graceful shutdown.

Panels that have already been closed are excluded from the count. If no agents are in Working or Running state, no dialog appears and Daintree quits silently. OS-level signals such as SIGTERM or a force-quit bypass the dialog entirely.

Preventing System Sleep

When any agent is in the Working or Running state, Daintree automatically prevents the system from sleeping. This keeps long-running agent tasks from being interrupted by macOS, Windows, or Linux power management. The protection stays active until every agent has left those states. There's nothing to configure and no indicator shown. It just works in the background.

Providing Codebase Context

Use CopyTree to give agents context about your codebase. Press Cmd+Shift+C to copy a structured snapshot to your clipboard, then paste it into any agent's terminal input. You can also right-click a worktree card and choose Copy Context to select between full context and modified files only.

Send Selection to Agent

Select text in any terminal or agent panel, then route it directly into another panel's input buffer without going through the system clipboard. This is the quickest way to share a snippet of agent output, an error message, or a shell result with another agent running in parallel.

There are three ways to trigger it:

• Right-click context menu — select text, then right-click and choose Send to Agent. The menu item only appears when text is selected in a PTY-backed panel.
• Keyboard shortcut — see the platform-specific shortcut below.
• Action palette — open with Cmd/Ctrl+Shift+P and search for "Send to Agent" (the action is listed as "Send terminal selection to another agent or terminal panel").

The palette shows a searchable list of all other PTY-backed panels (agent and terminal panels). Each item displays the panel title; agent panels also show the agent name and icon. The list caps at 20 results, so use the search field to find a specific target if you have many panels open. Panels in the trash or running in the background are excluded.

Panels whose input is currently locked (for example, while an agent is actively working) appear in the list but are greyed out with a lock icon. They cannot be selected as a target.

Daintree caches your selection as you highlight text, so the text does not need to remain highlighted when the palette opens. The last selection you made in that panel is used. After sending, the cached selection persists, so you can immediately route the same text to a second target without reselecting.

The selected text arrives in the target panel's input buffer as if you had typed it. It is not submitted automatically. Press Enter in the target panel to run it. Multi-line selections are handled safely through bracketed paste mode, so the content won't execute line-by-line on arrival.

To send the same input to multiple panels at once, see Bulk Operations.

Agent Updates

Daintree can check and update agent CLI versions. Updates work through:

• npm — npm install -g <package>
• Homebrew — brew upgrade <package>
• Custom command — per-agent update command

Check current agent versions and manage updates in the agent settings.

Custom Agents

Beyond the seven built-in agents, Daintree supports custom agents through the user registry. Custom agents merge with the built-in registry and show up alongside them in all launch surfaces.

For each custom agent, you can configure:

• Name — display name in the UI
• Command — the CLI command to execute
• Color — brand color for panel borders and badges
• Keyboard shortcut — quick-launch binding
• Context injection — whether CopyTree injection is supported

MCP Server

The sections above cover agents that run inside Daintree terminals. The MCP server flips this around: Daintree becomes the server, and external tools connect to it from outside.

Daintree exposes its action system as a local MCP server (Model Context Protocol). Any MCP-compatible client running on the same machine can connect and call Daintree actions as tools. This means an external agent like Claude Code or Cursor can read terminal output, manage worktrees, stage git changes, and control panels without needing to go through the terminal.

The server is opt-in and disabled by default. It binds to 127.0.0.1 only, so nothing is exposed to the network.

Enabling the Server

Open Settings > MCP Server and toggle the server on. It starts immediately. Toggle it off to stop.

No separate installation is needed. The server runs inside Daintree's main process and is available as long as Daintree is open.

Connecting an Agent

The Settings panel has a "Copy MCP config" button that copies a ready-to-paste JSON snippet to your clipboard:

{
  "mcpServers": {
    "daintree": {
      "type": "sse",
      "url": "http://127.0.0.1:45454/sse"
    }
  }
}

For Claude Code, paste this into .mcp.json at your project root, or add it globally in ~/.claude.json. You can also use the CLI:

claude mcp add daintree --transport sse http://127.0.0.1:45454/sse

If you have authentication enabled, the CLI command above won't include the bearer token. Use the JSON snippet from the Settings panel instead, as it includes the Authorization header automatically.

For Cursor, see the Cursor MCP docs. For Windsurf, see the Windsurf MCP docs. For other MCP clients, paste the snippet into their server configuration file.

Auto-Discovery

While the server is running, Daintree writes a discovery file at ~/.daintree/mcp.json containing the connection details. When the server stops (or Daintree quits), the entry is removed. Other keys in the file are left untouched.

This file is reserved for future dedicated integrations. Most users can ignore it and use the manual config steps above.

Available Tools

Tools exposed through MCP mirror Daintree's internal action system. The exact set depends on what's registered at runtime, but here are the main categories:

Tools marked (confirm) require explicit confirmation before they execute. Use actions.list to get the full manifest at runtime, including descriptions and input schemas for every tool.

Confirmation-Required Actions

Daintree groups actions into three danger levels:

• Safe — callable freely, no extra steps needed.
• Confirm — listed in the tool manifest, but the call must include _meta.confirmed: true in its arguments. Without it, the server returns a CONFIRMATION_REQUIRED error. The tool's description always notes this requirement.
• Restricted — never listed and never callable through MCP.

This prevents autonomous agents from running destructive operations (like deleting a worktree or sending a terminal command) without an explicit signal. The tool arguments for a confirm call look like this:

{
  "_meta": { "confirmed": true },
  "terminalId": "abc123",
  "command": "npm run build"
}

Authentication

By default, no authentication is required. Any process on 127.0.0.1 can connect. If you want to restrict access, generate a bearer token in Settings > MCP Server > Authentication.

With a token set, all requests must include the Authorization: Bearer <token> header. The "Copy MCP config" button automatically includes the header when a token is active:

{
  "mcpServers": {
    "daintree": {
      "type": "sse",
      "url": "http://127.0.0.1:45454/sse",
      "headers": {
        "Authorization": "Bearer daintree_abc123..."
      }
    }
  }
}

You can generate, regenerate, or remove the token at any time from the same Settings panel.

Port Configuration

The default port is 45454. You can change it in Settings > MCP Server. If the configured port is already taken, Daintree tries the next port up, repeating up to 10 times (maximum 45464). The Settings panel shows which port the server actually bound to if it differs from your configured value.

If all 10 candidate ports are unavailable, the server fails to start and the Settings panel shows the error.

Bulk Operations

When you're running multiple agents across several worktrees, managing them one at a time gets tedious fast. Bulk Operations lets you send a single action to every selected agent terminal at once. Open the palette, pick which worktrees to target, choose what to send, and fire it off.

Opening Bulk Operations

There are three ways to open the Bulk Operations palette:

• Keyboard shortcut — Cmd+Alt+Shift+B (macOS) or Ctrl+Alt+Shift+B (Windows/Linux). Cmd+Shift+B on its own arms every eligible agent in the current worktree for Fleet Arming instead.
• Toolbar button — click the broadcast icon in the toolbar
• Action palette — open with Cmd+Shift+P and search for "Bulk Operations"

See Keyboard Shortcuts for the full shortcut reference.

Selecting Worktrees

The palette lists every worktree in your current project. Each row shows the branch name, agent count, and the dominant agent state. Click a row to toggle its checkbox, or use Select All / Deselect All at the top to target everything at once.

Worktrees with no active agent terminals are greyed out and can't be selected. The footer displays a running count of selected worktrees and total agents that will receive the action.

State Filter Presets

Above the worktree list, four filter buttons let you quickly add worktrees by their current state:

• Active — agents in the Working or Running state
• Waiting — agents blocked on input or approval
• Idle — agents at the prompt, ready for a command
• Completed — agents that have finished their task

Each button shows a count of matching worktrees and adds them to your current selection (it won't deselect anything already chosen). Matching is based on the worktree's dominant agent state, so a worktree with one Idle and one Working agent would appear under Active (since Working is the dominant state). These states map directly to the Agent State Tracking definitions above.

Keyboard Navigation

The palette supports full keyboard navigation: ↑/↓ to move between worktrees, Space to toggle selection, Cmd+Enter to send, and Esc to go back or close.

Keystroke Mode

Keystroke mode sends a single key signal to every selected agent's terminal. Four presets are available:

Ctrl+C and Double Escape are considered destructive actions. When you select either one, an amber confirmation prompt appears before anything is sent. Double Escape sends two Escape keystrokes with a one-second delay between them.

Text Command Mode

Text Command mode types a message and submits it to every selected agent. This is useful for giving the same instruction to multiple agents at once, or for approving a batch of waiting prompts with a specific response.

Type your command in the input field, then press Enter to see a preview of the resolved text for each worktree. The preview step lets you verify everything looks right before confirming. Press Cmd+Enter to skip the preview and send immediately.

The input supports template variables that resolve differently for each worktree. Click the variable chips below the input to insert them at the cursor. See Template Variables below for the full list.

Command history is available with ↑/↓ arrow keys, storing up to 50 previous commands.

Recipe Mode

Recipe mode broadcasts a saved recipe to all selected worktrees. Recipes from all three scopes (Global, Team, and Project) are available for broadcast.

Select a recipe from the list, then preview which worktrees will receive it. After confirmation, recipes are dispatched three at a time through a concurrency queue to avoid overwhelming the system.

Template Variables

Template variables resolve per-worktree at send time. They're available in Text Command mode and appear as clickable chips below the input field. Variable values are pulled from each worktree's Git branch and linked GitHub issue or PR.

If a variable can't be resolved for a particular worktree (for example, no linked issue), it becomes an empty string. The preview step highlights any unresolved variables with an amber warning so you can catch them before sending.