Installing and Launching Agents

Installing Agents

Each agent is a separate CLI you install yourself. Install and authenticate one and Daintree picks it up on its next availability pass, with no configuration on your side.

Settings > CLI Agents reports the install and authentication status of every agent on the machine, which detection step found the binary, the path it would launch from, and what the auth probe looked for. The same panel links to each agent's install docs and can run its update command — npm, Homebrew, or a per-agent custom command, depending on how that CLI distributes itself.

Install commands, authentication steps, and resume specifics live on each agent's own page, linked from the table above.

Launching an Agent

There is one searchable launcher. It is the same surface whether you open it from the toolbar or from the dock's + button — same inventory, same rows, same keyboard model. Before v0.31 there were three separate surfaces (a toolbar agent tray, a panel tray, and the dock +), which meant three places to look and three places to drift apart. There is now one.

Type to filter across agents, panels, and recipes at once. Unfiltered, the list browses in bands:

• Recently launched — a capped quick-reach band, newest first. Agents here are deliberately repeated further down, so the Pinned heading never lies about what is pinned.
• Pinned and Other — the launchable agents, split by whether they have a toolbar button.
• Open in dock / Open in grid — panel kinds, grouped by where they will actually land rather than hidden when they cannot dock.
• Launch recipe — your recipes, with their scope shown on the right.
• Needs setup — installed agents that are not launchable yet. They are offered, not hidden, so there is always a route to finishing setup.

Each row carries the affordances that used to be scattered across trays and submenus:

• Pinning: press Alt+P on the selected row, or click its pin button, to add or remove its toolbar button. Agents and panels write to their own toolbar stores behind the one affordance.
• Shortcut capture: record a keyboard shortcut for an agent in place, without going to Settings.
• Preset rows: an agent with presets expands into sibling rows — Default first, then CCR Routes, Project Shared, and Custom. They are siblings rather than a submenu so arrow-key navigation stays in one list.
• Running-state pips: a colored dot shows the dominant state of that agent's live runs, so you can see what is already working before you start another.

Agents also launch straight from a bound keyboard shortcut, from the agent buttons on a worktree card, and from the toolbar buttons of pinned agents. However you start one, it launches in the active worktree's directory with the right branch and working tree from the start, using that worktree's active preset.

View full size:

When an Agent's CLI Isn't Available

Every agent resolves to one of five availability states. Daintree probes in layers: PATH first (which -a on macOS and Linux, where.exe on Windows), then the agent's known native install paths, then an npm-global bin probe for npm-distributed CLIs, then WSL on Windows for agents that only ship a Linux binary. A separate passive authentication probe runs alongside it, so installed-but-not-signed-in is distinguishable from installed-and-ready.

Ready and Unauthenticated both count as launchable. Anything except Missing counts as installed.

The launch gate

Selecting an agent whose CLI is not launchable no longer deep-links you into Preferences. It opens a launch gate in the panel the agent would have occupied — the launch is held, not cancelled. The gate shows:

• A diagnostic banner naming the actual state: binary not found, detected in WSL, blocked by security software, or sign-in not detected. Where Daintree has one, it prints the last known path.
• The install commands for your OS, taken from the agent's registry entry, each one copyable, plus that agent's troubleshooting notes.
• Re-check, which forces an availability probe past its usual throttle. If the CLI has become launchable, the gate continues the launch it stood in for, resolving the command against the path the probe just found.
• Run anyway, which proceeds with the original launch regardless. Use it when you know the binary works and the probe is wrong — a wrapper script, an unusual shell environment.
• Agent settings and a Docs link, as secondary routes.

Unlaunchable rows in the launcher say so before you select them: "… needs setup. Select to see recovery options", or "… is blocked by endpoint security. Select to see recovery options".

Alt-Screen vs Inline Mode

A terminal CLI can draw itself two ways. Alt-screen mode takes over the alternate screen buffer and repaints a full-screen TUI, which is what the CLI does natively. Inline mode writes ordinary lines into Daintree's own scrollback, which keeps WebGL scrollback, search, and clean resize behavior. Neither is universally better; inline is smoother inside a tiled panel, alt-screen matches what the CLI looks like in your own terminal.

The decision resolves from three levels, most specific first: a preset override, then the agent's own setting, then the global "Use alt-screen mode by default" switch in Settings > CLI Agents. The per-agent and per-preset controls are tri-state — Default (inherit), Inline, or Alt screen — so an explicit choice at a narrower scope always beats a broader one.

The global switch is off by default, and no shipped agent pins a curated default of its own, so every untouched agent resolves to "inline". What that means in practice depends on whether the CLI has a flag for it:

• OpenCode (--mini), Codex (--no-alt-screen), and Grok (--no-alt-screen) declare an inline flag, so they launch inline.
• Every other agent declares no inline flag and rides its own CLI default, which is alt-screen. Turning the global switch on changes nothing for them — there is no flag to inject.
• Grok is the one agent that also declares the opposite flag: choosing alt-screen for Grok passes --fullscreen, forcing full-screen rather than merely allowing it.

The alt-screen control only appears in Settings for agents that declare a flag in one direction or the other. For everything else the setting would have nothing to do.

Permission Bypass

Most agent CLIs ask before they edit a file, run a command, or reach the network. Every one of them also ships a flag that turns those prompts off. Daintree can inject that flag for you, and treats it as the high-blast-radius setting it is.

Settings > CLI Agents > Skip permission prompts for agents is the global switch. It defaults off. It is a live override, not a stored default: it is evaluated at flag-generation time on every spawn, restart, restore, and resume, and it never rewrites your per-agent choices. Turn it off and the flag stops being injected immediately, including into sessions that were captured while it was on. It applies to agent terminals only — Daintree Assistant sessions carry their own separate setting.

Per agent, and per preset, the control is tri-state:

• Default (inherit) — defer to the next level up.
• On — force bypass on for this scope, even for an agent the global switch would not touch.
• Off — a true veto. A preset set to Off beats an agent set to On, and an agent set to Off beats the global switch. The narrower scope always wins, so an explicit denial can never be overridden from further out.

The global switch is deliberately narrower than an explicit choice: it only reaches agents that declare bypass support in the registry, which today means Claude Code and Codex. Every other agent needs its own On before Daintree will pass its bypass flag — the global switch will not silently hand a dangerous flag to an agent that has not opted in.

The flag injected for each agent:

Four agents have no bypass flag at all, so the setting does nothing for them. OpenCode is the one worth calling out: it does have a skip-permissions flag, but only on its run subcommand, not on the interactive TUI launch Daintree uses. It is excluded deliberately rather than by oversight, so there is nothing to look for.

When a scope resolves to bypass-on, the Settings editor shows the exact flag it will append to the command, so the consequence is visible before you launch.