UI Layout

Overview

Canopy's interface is organized into five main areas:

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

Toolbar

The toolbar runs along the top of the window, split into 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 these anchors, with a left group and a right group that each respond to available width.

When the window is too narrow to show every button, lower-priority buttons automatically collapse into a ... overflow menu. All buttons remain accessible regardless of window size.

Responsive Overflow

Canopy assigns every toolbar button a priority tier. When the window narrows and space runs out, buttons are removed from the visible toolbar starting with the lowest priority (tier 5) and placed into a ... overflow dropdown. Widening the window brings them back. A small hysteresis buffer prevents buttons from flickering in and out at boundary widths.

Within the same tier, buttons further to the right overflow first. A few additional details worth noting:

• When GitHub Stats moves into the overflow menu, it expands into three separate items (Issues, Pull Requests, and Commits) each showing their count.
• If GitHub Stats or the Notification Center have an open dropdown when they overflow, the dropdown is automatically closed.
• The Project Switcher pill in the center also responds to width. Below roughly 700px, the branch name text hides and only the branch icon remains.

Customizing the Toolbar

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

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

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

Launcher Palette Settings

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

• Always show dev server in launcher — displays 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. Options include None (first available), Terminal, Claude, Gemini, Codex, OpenCode, Browser, and Dev Preview.

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

Sidebar

The sidebar lists all worktrees in the current project. Each worktree appears as 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 always appear at the top. Below the worktree list, the QuickRun panel lets you fire off terminal commands without setting up a full Recipe. See Terminals & Panels for details on QuickRun, and Worktrees for details on worktree cards.

Panel Grid

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

Grid layout is configurable — see Terminals & Panels for layout strategies (automatic, fixed columns, fixed rows) and the two-pane split option.

Portal

The Portal is a built-in browser panel on the right side of the window, for chatting 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 does not close it. The session keeps running in the background, and you can preview or restore it at any time. The dock bar only appears when at least one panel is docked, and it shows panels for the active worktree.

Dock Pills

Each docked panel appears as a compact pill in the dock bar. Pills show 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 when the agent is actively working. Idle or completed panels render at reduced opacity so 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 provides full access to the panel while it remains docked.

Inside the popover, you can restore the panel to the grid in 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 several 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 automatically shifts to the dock pill. From there, press Enter or Space to open the popover preview.

All panel types work with the dock: agent panels, terminals, browsers, and dev previews. See Terminals & Panels for more on panel types.

Keyboard Navigation

Ctrl+Tab and Ctrl+Shift+Tab cycle through all panels 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.

See Keyboard Shortcuts for the full shortcut reference.

Action Containers

On the right side of the dock bar, separated from the main pills, are three action containers:

• Background — panels that have been deliberately backgrounded. Click to see a list and restore individual panels.
• Waiting — panels with agents in a waiting state, grouped for quick access.
• Trash — deleted terminals awaiting permanent removal, with an option to restore.

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

Dock Density

The dock density setting controls the height and spacing of dock pills. You'll find it in Settings > Appearance > App under Dock Density.

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

Palettes

Canopy provides several palette overlays for navigation and commands. Only one palette can be open at a time.

Action Palette

The Action Palette lists every available command in Canopy. Press Shift twice in quick succession (within 300ms) to open it, or use Cmd+Shift+P. This works similarly to JetBrains' "Search Everywhere" or VS Code's command palette.

With no search query, the palette shows your most recently used actions first, followed by the rest alphabetically. Start typing to fuzzy-search across action titles, categories, and descriptions. Up to 20 results are shown at a time.

Each result displays a color-coded category badge (terminal, agents, navigation, git, and others), the action title, a short description, and the keyboard shortcut if one is assigned. Actions that aren't available in the current context appear greyed out with a tooltip explaining why.

Quick Switcher

Press Cmd+P to open the Quick Switcher and jump to any open terminal or worktree. With no search query, results are sorted by most recently used, so your last-focused panel is always at the top. Typing a query triggers fuzzy search with a boost for recently used items.

Each result shows the agent icon, a type badge (terminal or worktree), and a subtitle with the working directory or worktree path. Backgrounded panels are marked accordingly. Selecting a terminal from a different worktree switches to that worktree automatically.

For the full shortcut reference, see Keyboard Shortcuts.

Context Menus

Every panel and worktree card in Canopy has a right-click context menu built with Radix UI. These menus follow your app theme, display inline keyboard shortcut hints, and support full keyboard navigation (arrow keys, Enter, Escape, and submenu traversal via left/right arrows).

There are several ways to open a context menu:

• Right-click anywhere within a panel (terminal content, browser, notes, or dev preview)
• Right-click a dock tab in the dock (the tab bar at the bottom of the panel grid) or a tab group
• Shift+F10 opens the context menu for the currently focused panel
• Action Palette: search for "Open Context Menu"
• Right-click a worktree card in the sidebar, or click the ... button on the card header
• Right-click empty space in the panel grid to open the Panel Palette

Terminal and Agent Panel Menu

Right-clicking a terminal or agent panel reveals the most feature-rich context menu in Canopy. Agent-only items are noted below.

Clipboard

• Copy (Cmd+C on macOS) copies the terminal selection. On Windows and Linux, Ctrl+C sends an interrupt signal, so use the context menu item directly. Disabled when no text is selected.
• Paste (Cmd+V / Ctrl+Shift+V).
• Send to Agent (Cmd+Shift+E / Ctrl+Shift+E) forwards the selected text to the agent input. Disabled when no text is selected.
• Open Link / Copy Link Address appear only when you right-click over a detected URL (http, https, or ftp). Trailing punctuation is stripped automatically.

Layout

• Move to Worktree (submenu) lists all other worktrees. Only shown when the project has more than one worktree.
• Move to New Worktree... creates a worktree and moves the panel there. Agent panels only.
• Move to Dock / Move to Grid toggles the panel between dock and grid placement.
• Maximize / Restore Size (Ctrl+Shift+F) expands or restores a panel. Grid panels only.

Terminal actions

• Restart Terminal restarts the PTY process.
• Redraw Terminal redraws the renderer, useful for fixing display glitches.
• Force Resume (Paused) only appears when a terminal is paused due to output backpressure. This is a rare edge case, but the option is there when you need it.
• Lock Input / Unlock Input toggles whether keyboard input reaches the terminal.
• Watch Terminal / Cancel Watch (Cmd+Shift+W / Ctrl+Shift+W) subscribes to activity notifications for the panel. Agent panels only. See Notifications & Sound.
• Create Note creates a timestamped note pre-filled with the agent name, worktree, and any selected text. Agent panels only. See Notes.

Identity and management

• Convert to (submenu) lets you switch a panel between Terminal, Claude, Gemini, Codex, OpenCode, and Cursor. The current type is disabled in the list. Only shown for agent panels or terminals that can be converted.
• Duplicate Terminal, Rename Terminal, View Terminal Info
• Send to Background moves the panel out of the grid without closing it.
• Trash Terminal soft-closes the panel.
• Kill Terminal hard-kills the PTY process. This is a destructive action highlighted in red.

Browser Panel Menu

Browser panels share the same layout actions (Move to Worktree, Move to Dock/Grid, Maximize/Restore), plus:

• Reload Page
• Open in Browser opens the current URL in your system browser. Disabled when no valid URL is loaded.
• Copy URL copies the current page URL. Disabled when no valid URL is loaded.
• Duplicate Browser, Rename Browser
• Send to Background, Close Browser, Remove Browser (destructive)

Notes Panel Menu

Notes panels have the shared layout actions, plus:

• Rename Note
• Reveal in Notes Palette jumps to the note in the Notes Palette.
• Send to Background, Delete Note (destructive), Close Note

Dev Preview Panel Menu

Dev Preview panels have the shared layout actions, plus:

• Reload Preview
• Open in Browser, Copy URL (disabled when no valid URL)
• Duplicate Dev Preview, Rename Dev Preview
• Send to Background, Close Dev Preview, Stop Dev Server (destructive)

Worktree Card Menu

Right-click any worktree card in the sidebar, or click the ... button on the card header. Both open the same menu with identical items.

• Launch (submenu) opens a new panel: Claude, Gemini, Codex, OpenCode, Cursor, Terminal, Browser, or Dev Preview.
• Open Panel Palette
• Sessions (submenu) provides bulk actions: Dock All, Maximize All, Restart All, Reset All Renderers, Close Completed, Close All, and End All (destructive). Each item shows a count of affected panels.
• Attach to Issue... / Change Issue... links the worktree to a GitHub issue.
• View Plan opens the worktree's plan file (only shown when one exists).
• Review & Commit opens the Review Hub.
• Compare Worktrees...
• Revert Agent Changes restores the worktree to its snapshot. Only shown when a snapshot exists.
• Copy Context (submenu): Full Context or Modified Files Only.
• Open in Editor, Reveal in Finder, Copy Path
• Pin to Top / Unpin, Collapse Card / Expand Card
• Open Issue / Open PR (submenus) open linked issues or PRs in the Portal or external browser.
• Run Recipe (submenu) launches a saved recipe. Only shown when recipes exist.
• Save Layout as Recipe saves the current panel arrangement as a recipe.
• Delete Worktree... (destructive)

See Worktrees for full details on worktree management.

Empty Grid Right-Click

Right-clicking on empty space in the panel grid (where no panel is under the cursor) opens the Panel Palette, letting you launch a new panel directly from where you want it.

Window Behavior

macOS

On macOS, Canopy uses a hidden inset title bar — the traffic lights are inset and content extends 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

Cmd+W is intercepted by Canopy — instead of closing the window (which would kill all your terminals), it closes the currently focused panel. This prevents you from accidentally losing running agent sessions.

Window State

Canopy 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. If no saved state exists for a project, the new window cascades 30px from the most recently used window.

Multiple Windows

You can open multiple Canopy windows at the same time, each displaying a different project. This lets you work across projects side by side without constantly switching contexts.

There are three in-app ways to open a new window:

1. Keyboard shortcut — press Cmd+Shift+Alt+N to open a new window. You'll be prompted to select 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 when you hold Cmd.

Switching projects within a single window replaces what that window shows. Multiple windows let you actually 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 (e.g. canopy /path/to/repo) while Canopy 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.