UI Layout

Overview

The Daintree window is divided into five areas:

• Toolbar: top bar with the project switcher, agent launchers, and quick actions
• Sidebar: left panel listing worktrees and their terminals
• Panel Grid: central area holding every open terminal and content panel
• Dock: bottom bar for panels moved out of the grid; they keep running while docked
• Portal: optional right panel with an embedded browser

Toolbar

The toolbar runs along the top of the window in three zones. The Sidebar Toggle is anchored on the far left, the Portal Toggle on the far right, and the Project Switcher pill sits in the center. Agent launchers and tools fill the space between those anchors, split into a left group and a right group that each respond to available width.

When the window is too narrow to show every button, the lower-priority ones collapse into a ... overflow menu. Every button stays reachable no matter how narrow the window gets.

Responsive Overflow

Every toolbar button has a priority tier. When the window narrows and space runs out, buttons drop off the visible toolbar lowest priority first (tier 5) and move into a ... overflow dropdown. Widen the window again and they come back. A small hysteresis buffer keeps buttons from flickering in and out at boundary widths.

Within a tier, buttons further to the right overflow first. A few details to keep in mind:

• When GitHub Stats moves into the overflow menu, it splits into three separate items (Issues, Pull Requests, and Commits), each showing its count.
• If GitHub Stats or the Notification Center have a dropdown open when they overflow, that dropdown closes.
• Voice Recording stays pinned in the visible toolbar for as long as a dictation session is active, whatever the width. The hardware recording indicator never disappears into the overflow tray.
• The Project Switcher pill in the center responds to width too. Below roughly 700px, the branch name text hides and only the branch icon stays.

Pinning, Unpinning, and Plugin Buttons

Right-click any toolbar button, built-in or plugin-contributed, and pick Unpin from Toolbar to move it into the overflow tray without opening Settings. Right-click the same button in the overflow tray to pin it back. This state lives in the same toolbar layout Settings edits, so an unpinned button shows up in Settings as a dimmed row you can re-enable. Toggling visibility off in Settings is how you hide a button from the overflow tray entirely.

Plugin buttons appear in Settings > Toolbar alongside the built-ins, each with its own show/hide checkbox and drag handle. Use Settings when you want to hide a plugin button entirely rather than just move it to the overflow. See Plugin System for how plugins contribute toolbar buttons.

Customizing the Toolbar

Open Settings > Toolbar to rearrange and configure toolbar buttons. The left-side and right-side button groups each get their own list.

• Reorder buttons by dragging them within a list.
• Show or hide individual buttons with the checkbox next to each entry. Hidden buttons appear dimmed and can't be dragged until you re-enable them.
• The Sidebar Toggle and Portal Toggle are fixed anchors. They don't appear in the configurable lists.
• Reset to Defaults, at the bottom of the tab, restores the factory button order and visibility.

Your toolbar preferences (button order, hidden buttons, launcher settings) are stored locally and persist across restarts. When Daintree adds new buttons in a future update, they're merged into your custom layout at their default position, leaving your existing order intact.

Launcher Palette Settings

The Launcher Palette section within Settings > Toolbar controls how the panel launcher palette (Cmd+N) behaves. There are two options:

• Always show dev server in launcher: keeps the Dev Server option in the palette even when no dev command is configured in project settings.
• Default selection: sets which panel type is pre-selected when the palette opens. The options are None (first available), Terminal, Claude, Gemini, Codex, OpenCode, Browser, and Dev Preview.

See Terminals & Panels for the panel types you can launch.

Project Switcher Pill

The pill in the center of the toolbar shows the current project name and branch. Right-click it for a context menu of project-level actions:

• Pin to Top / Unpin pins or unpins the project at the top of the Project Switcher palette.
• Copy Path copies the absolute project path to the clipboard.
• Project Settings opens the project-scoped settings tab.
• Stop All Agents ends every running agent session across all worktrees in this project. It only shows when at least one agent is running.
• Close Project closes the project in the current window.

Selecting the active project from the Project Switcher palette does nothing. The palette stays put and nothing reloads, since the project is already showing.

Sidebar

The sidebar lists every worktree in the current project. Each one is a card showing its branch, mood, linked issues, and terminal panels.

• Toggle: Cmd+B
• Resize: drag the sidebar edge (default width: 350px)
• Width persists across sessions

Pinned worktrees sit at the top. Below the worktree list sits the QuickRun panel; see QuickRun for what it does, and Worktrees for worktree cards.

Keyboard Model

The worktree list is a single tab stop. Press Tab once to focus the list, then use the arrow keys to move between cards. Focus stays on the list container while the active row is tracked through aria-activedescendant, so screen readers always announce the right card.

Each row has two keyboard modes:

• List mode (default): ArrowUp / ArrowDown move between worktree cards. j and k are vim-style aliases. Home and End jump to the first or last card. PageUp / PageDown move by a screenful.
• Toolbar mode: Enter or ArrowRight drops into the focused row's inline toolbar (Launch, Review, and the other per-row controls). ArrowLeft and ArrowRight then cycle through the toolbar items. Escape, or ArrowLeft at the start of the toolbar, returns to list mode.

Reordering Worktrees

Reorder a worktree from the keyboard with Alt+ArrowUp / Alt+ArrowDown. Focus stays on the moved card, and the screen-reader announcement reports the new position once the key release settles, so a held key doesn't fire an announcement per step.

With the mouse, drag a worktree card to a new position. A thin directional line appears above or below the target row to show exactly where the card will land. Press Escape mid-drag to cancel; the card snaps back to where it started with an assertive "drag cancelled" announcement.

Panel Grid

The panel grid holds all your terminals, browsers, and other panels. It shows the panels for the currently selected worktree.

The grid layout is configurable. See Terminals & Panels for the layout strategies (automatic, fixed columns, fixed rows) and the two-pane split option.

Tab Overflow

When a panel has more tabs than fit in the header strip, the extra ones collapse behind a chevron overflow button at the right end of the strip. Click the chevron for a list of the hidden tabs; clicking an entry switches to it. Visible tabs keep their order, and the overflow set is recomputed every time the grid resizes or a new tab opens.

The active tab always stays visible. If you switch to a tab that's currently off-screen, the strip auto-scrolls horizontally to bring it into view.

Tab Keyboard and Drag

When the tab strip has focus, ArrowLeft / ArrowRight cycle between tabs and Home / End jump to the first or last. You can also drag tabs horizontally within the strip to reorder them inside the same panel group.

Empty States

When a worktree is active but its grid has no panels, the empty state shows a project identity card: the project icon, name, current branch, and absolute path. A RecipeRunner control row sits underneath for launching saved recipes, alongside a Project Pulse snapshot of recent project activity. A rotating tip line at the bottom surfaces one habitat hint each time you land here.

When no worktree is selected at all, the grid shows a simpler empty-state card with one clear next step. That's Select a worktree when worktrees exist but none are active, or Open a Git repository to get started when the project has no worktrees yet. The second case exposes a primary Open directory… button.

Right-clicking empty grid space still opens the Panel Palette directly, whichever empty state is showing.

Portal

The Portal is a built-in browser panel on the right side of the window. Use it to chat with Claude, ChatGPT, or Gemini alongside your agent terminals.

• Toggle: Cmd+\
• Launchpad: quick-access buttons for detected AI chat services
• Tabs: run multiple AI chat sessions side by side

See Portal Browser for full details.

Dock

The dock is a fixed bar along the bottom of the window that holds panels you've moved out of the main grid. Moving a panel to the dock doesn't close it. The session keeps running in the background, and you can preview or restore it whenever you want. The dock bar only appears once at least one panel is docked, and it shows the panels for the active worktree.

Dock Pills

Each docked panel shows up as a compact pill in the dock bar. A pill carries the agent or terminal icon, color-coded to the agent type, a truncated title, and optionally the current command or activity status in a monospace span. A state icon, such as a spinner, appears while the agent is working. Idle or completed panels render at reduced opacity so the active ones stand out.

Pills support three interactions:

Popover Preview

Clicking a dock pill opens a floating popover above it with a live preview of the panel content. The popover is resizable and gives you full access to the panel while it stays docked.

From inside the popover you can restore the panel to the grid two ways: click the Restore button in the popover header, or double-click the panel header itself. Both move the panel back into the grid layout. Press Escape or click outside the popover to close it without restoring.

Moving Panels to and from the Dock

There are a few ways to move panels between the grid and the dock:

When you use Cmd+Alt+M to send a panel to the dock, keyboard focus moves to the dock pill. From there, press Enter or Space to open the popover preview.

Every panel type works with the dock: agent panels, terminals, browsers, and dev previews. See Terminals & Panels for the panel types.

Drag-and-Drop into the Dock

You can also drag a panel header straight into the dock bar to dock it. While the drag hovers over the dock, the bar lights up with a drop-armed ring so you can tell the target is accepting the drop. The cursor switches to a copy-cursor over the dock, and a no-drop cursor over anything that can't take the panel.

When the dock is empty and you start dragging a panel, a ghost Trash pill appears at the right end of the bar. Drop onto it to send the panel to the trash in one motion. The ghost pill disappears the moment the drag ends.

Keyboard Navigation

Ctrl+Tab and Ctrl+Shift+Tab cycle through every panel in the active worktree, grid panels first, then dock panels. When the cycle reaches a docked panel, its popover opens automatically so you can see the content without leaving the keyboard.

The dock bar itself is a single tab stop. Once it's focused, ArrowLeft / ArrowRight move focus between pills, Home and End jump to the ends, and Enter or Space activates the focused pill. If the dock overflows horizontally, the focused chip auto-scrolls into view as you navigate. While a panel is being dragged, the drag handler takes over the keyboard, so the arrow keys move the dragged pill instead of moving focus.

See Keyboard Shortcuts for the full shortcut reference.

Action Containers

On the right side of the dock bar, set apart from the main pills, are four action containers:

• Background: panels you've deliberately backgrounded. Click to see the list and restore individual panels.
• Waiting: panels with agents in a waiting state, grouped for quick access.
• Errors: panels whose agent session has errored out, grouped so you can triage failures in one place instead of hunting through the rest of the dock.
• Trash: soft-deleted terminal and agent panels awaiting permanent removal, each with a Restore action. The popover lists entries in LIFO order, so the most recently trashed panel sits at the top.

In compact dock density mode these containers show only an icon with a count badge. In normal and comfortable modes they show a full label like "Background (3)".

Trash holds terminals and agent panels. Browser, Dev Preview, and Review panels use Close and Remove from their context menus rather than Trash, since they don't carry stateful sessions that need recovery.

Dock Density

The dock density setting controls the height and spacing of dock pills. It lives in Settings > Appearance > App under Dock Density.

The change applies immediately, no restart needed. Compact mode also drops the action containers on the right side of the dock to icon-only display, leaving more horizontal space for dock pills.

You can change density on the fly too: right-click an empty area of the dock bar and pick Dock density → Compact, Normal, or Comfortable. The submenu shows a radio mark next to the current density, and the choice is the same setting Settings holds. Handy when you want to free up dock space without opening a settings tab.

Palettes & Menus

Daintree drives navigation and commands through palette overlays (the Action Palette, Quick Switcher, Panel Palette, Worktree Palette, and Project Switcher) and a right-click context menu on every panel and worktree card. These keyboard-driven surfaces have their own canonical page: Palettes & Menus. That's where to find frecency-ranked action search, fuzzy panel switching, and the full per-panel and worktree-card menu reference.

Status Banners

Transient status messages across the workspace share one banner chrome. A snapshot restore notice, a degraded file-watcher warning, a settings-sync conflict, a plugin-load failure: the layout is the same every time. A severity icon, a short title, a description line, and optional action buttons on the right. The chrome stays consistent across every surface (workspace, panel, settings dialog), so a banner means the same thing wherever it shows up.

Banners use the standard severity palette: error (red), warning (amber), info (blue), success (green), and neutral. The close affordance sits in the same spot on every banner, and any banner with an attached action puts its label inline rather than hiding it behind a menu.

Window Behavior

Cold-Start Animation

On launch, Daintree swaps its loading skeleton for the live workspace through one coordinated fade rather than piecemeal pop-in. The toolbar, sidebar, panel grid, and dock settle into place together, so the first frame after load feels deliberate instead of jittery. On reduced-motion systems the animation is skipped and the workspace just appears.

macOS

On macOS, Daintree uses a hidden inset title bar: the traffic lights are inset and content runs to the top edge of the window. The app uses simple fullscreen mode, which extends into the notch area on newer MacBooks.

Window Close Protection

Daintree intercepts Cmd+W. Instead of closing the window, which would kill all your terminals, it closes the currently focused panel. That keeps you from accidentally losing running agent sessions.

Window State

Daintree remembers your window size, position, and whether it was maximized or in fullscreen. State is saved per project path, so each project restores its own window geometry when you reopen it. With no saved state for a project, the new window cascades 30px from the most recently used window.

Multiple Windows

You can open several Daintree windows at once, each showing a different project. That lets you work across projects side by side without constantly switching contexts.

There are three in-app ways to open a new window. The shortcuts below show the macOS keys; on Windows and Linux, swap Cmd for Ctrl. See Keyboard Shortcuts for the full cross-platform reference.

1. Keyboard shortcut: press Cmd+Shift+Alt+N to open a new window. Daintree prompts you to pick a project.
2. Project Switcher context menu: open the Project Switcher (Cmd+Alt+P), right-click any project, and choose Open in new window.
3. Project Switcher modifier: in the Project Switcher, highlight a project and press Cmd+Enter to open it in a new window. The palette footer shows this hint while you hold Cmd.

Switching projects within a single window replaces what that window shows. Multiple windows let you view and work in two projects at the same time.

You can also press Alt+Enter in the Project Switcher to open a project in the background without switching focus. This loads the project so it's ready when you need it, without interrupting your current work.

Opening a path from the command line (for example daintree /path/to/repo) while Daintree is already running creates a new window for that path automatically.

See Keyboard Shortcuts for the full shortcut reference, and Projects for more on project management.