Terminals & Panels

Panel Types

Canopy has five panel types, each with its own accent color so you can tell them apart at a glance:

Creating Panels

• New terminal: Cmd+Alt+T (or Cmd+T to duplicate the focused panel; seeds from the last-closed config when no panels are open — see Keyboard Shortcuts for details)
• New agent: Cmd+Alt+C/G by default (Codex/OpenCode can be bound in Keyboard settings)
• Panel palette: Cmd+N to create any panel type

Managing Panels

Panel Focus Mode

Focus Mode gives a single panel the entire window. The sidebar disappears completely and the focused panel fills all available space. It's useful when you want to concentrate on one agent's output without the distraction of other panels and navigation.

Entering Focus Mode

• Double-click the panel header: click the header's drag area (the title or icon zone, not the tab bar or control buttons)
• Keyboard: Cmd+B
• Toolbar: click the sidebar toggle button (the panel icon in the toolbar)
• Action Palette: Cmd+Shift+P, then search for "Toggle Focus Mode"

What changes while in Focus Mode

The sidebar is fully hidden (not just collapsed) and the panel header updates to reflect the new state. An Exit Focus button appears in the header controls, giving you a clear way back. If you have other panels open in the grid, a background indicator appears in the center of the header showing how many panels are running behind the scenes. Panels that are actively working show an animated pulse alongside their count.

Exiting Focus Mode

• Double-click the panel header again
• Click the Exit Focus button in the header
• Press Cmd+B
• Click the toolbar sidebar toggle button

Focus Mode state is saved per project. When you reopen a project, Canopy restores whichever mode you were last using, including your original sidebar width and diagnostics panel state.

Panel Tabs

When a panel accumulates two or more sessions, the header switches from a single title to a tab bar. Each tab shows the panel's icon, a truncated title, and a hover-reveal close button. Single-tab panels keep the standard header, with a + button that appears on hover to let you start adding tabs.

Creating Tabs

The Cmd+T (Ctrl+T on Windows/Linux) shortcut pulls double duty: when a panel is focused, it duplicates that panel as a new tab alongside it. You can also click the + button that appears in the panel header (on hover for single-tab panels, or at the right end of the tab bar once multiple tabs are showing).

Both methods create a new session of the same panel type. Agent panels also display a state badge (spinner for working, pause icon for waiting) next to the title so you can track progress across tabs without switching.

Navigating Tabs

These shortcuts work globally from anywhere in the panel and wrap around at the edges (last tab jumps to first, and vice versa). When the tab bar itself has keyboard focus, you can also use ArrowLeft and ArrowRight to move between tabs, or Home and End to jump to the first or last tab.

Tab Overflow

When tabs exceed the visible width of the panel header, scroll arrows appear at the edges of the tab bar. A right-facing chevron shows up when there are tabs hidden to the right, and a left-facing chevron appears once you've scrolled away from the start. Each arrow sits on a gradient fade that smoothly blends the cut-off edge into the panel background.

Clicking an arrow scrolls the tab bar by roughly 80% of its visible width, giving you a smooth page-through feel. Switching to any tab (by click or keyboard shortcut) automatically scrolls it into view, so you never lose track of the active tab even with many tabs open.

Managing Tabs

• Rename: double-click a tab title to edit it inline. Press Enter or click away to confirm, Escape to cancel.
• Reorder: drag a tab left or right within the bar to rearrange the order.
• Close: hover any tab to reveal its × button and click to close. The active tab automatically switches to the nearest neighbour before closing.

Quick Switcher

Press Cmd+P to open the Quick Switcher, which lets you jump to any open terminal or worktree by name.

Panel Grid Layout

The main content area arranges panels in a configurable grid. Pick your layout strategy in Settings > Panel Grid:

Two-Pane Split Layout

Enable a side-by-side split in Settings > Panel Grid. Panels arrange into a two-pane view with a configurable ratio (20–80%). There's also a "prefer preview" option that automatically places browser and dev preview panels in the secondary pane.

Moving Panels

Use directional shortcuts to move focus between panels:

• Cmd+Alt+Arrow — move focus left, right, up, or down

You can also drag terminals between worktrees using the sidebar's drag-and-drop targets.

Terminal Features

PTY Emulation

Canopy uses node-pty for native PTY processes and xterm.js for rendering. You get full terminal emulation — colors, cursor positioning, alternate screen buffers, and image protocols (sixel and iTerm2).

Process Icons

Terminal tabs automatically show an icon for the process running inside them. When you start node, the tab switches from the generic terminal icon to a Node.js icon. Run python, and you get a Python icon. This works across every surface where terminal tabs appear: the panel header, tab bar, dock, worktree sidebar, and Quick Switcher.

Canopy's process detector scans the child process tree of each terminal's PTY and matches running executables against a built-in set of recognized processes. The following table lists all recognized non-agent processes, grouped by category. Agent processes are covered separately below.

When multiple recognized processes are running in the same terminal, the detector picks the highest-priority one. AI agent processes (Claude Code, Gemini CLI, Codex CLI, OpenCode, Cursor) always take priority, followed by package managers, then language runtimes, build tools, and infrastructure. Once the process exits, the icon reverts to the generic terminal icon. Running an agent CLI like claude in a plain terminal will show that agent's brand icon on the tab.

Dedicated agent panels are the one exception: they always display their own brand icon regardless of what's running inside them. If you run npm install inside a Claude Code agent panel, the tab still shows the Claude icon, not the npm icon.

Adaptive Refresh Rates

Terminal rendering adapts its refresh rate based on visibility and focus — this saves real resources when you have many panels open:

High-Performance Data Flow

Terminal data flows through SharedArrayBuffer ring buffers for zero-copy, low-latency transfer between the main process and renderer. This skips IPC serialization overhead — it matters when agents are producing a lot of output.

Scrollback

Configure scrollback history in Settings > Terminal:

• 500 lines — minimal memory footprint
• 1,000 lines (default) — good balance
• 2,500 lines — moderate buffer
• 5,000 lines — full history

The settings panel shows an estimated memory usage for your chosen scrollback size.

Performance Mode

Enable Performance Mode in Settings > Panel Grid to reduce resource usage on lower-end hardware. This reduces scrollback buffers and disables visual animations.

Hybrid Input Bar

An optional text field above each terminal that gives you a normal editing experience — selection, cursor movement, clipboard — before sending input to the PTY. Toggle it in Settings > Panel Grid, with an optional auto-focus setting.

Clipboard

All PTY-backed panels (terminal and agent panels) support VS Code-style copy and paste. Keyboard shortcuts, right-click context menu items, and clipboard image handling all work the way you'd expect from a modern terminal.

Keyboard shortcuts

Pasted text is automatically wrapped correctly for shells that support bracketed paste mode, so multi-line content won't execute prematurely.

Right-click context menu

Right-clicking anywhere in a terminal or agent panel opens a context menu with Copy, Paste, and Send to Agent at the top. Copy and Send to Agent are disabled when no text is selected. All items display the platform-appropriate keyboard shortcut inline. You can also press Shift+F10 to open the menu from the keyboard.

If you right-click over a detected URL, additional Open Link and Copy Link Address items appear. The menu also includes layout controls, terminal management actions, and panel-type-specific options. For the complete context menu reference covering all panel types, see UI Layout: Context Menus.

The context menu also includes a Send to Agent item when text is selected in a PTY panel. This routes the selection as typed input into another panel's input buffer without touching the clipboard. See Send Selection to Agent on the Agents page for full details.

Clipboard image paste

Paste a screenshot or image from your clipboard into any terminal panel, and Canopy saves it as a PNG file in a temporary directory. The shell-escaped absolute path is then inserted at the cursor, ready to pass directly to CLI tools or agent commands.

Pasting an image in the Hybrid Input Bar works the same way, with the addition of a thumbnail preview chip displayed inline alongside the path.

Gemini clipboard image access

Gemini CLI sandboxes file access to the current workspace by default. The Share Clipboard Directory setting (in Settings > CLI Agents > Gemini) injects the clipboard temp directory into Gemini's allowed paths so it can read pasted images. This is enabled by default.

File drag-and-drop

You can also drag files from Finder or your file manager directly onto a terminal panel. Canopy inserts the shell-escaped absolute paths at the cursor, the same way clipboard image paste works.

Search

Press Cmd+F to search within a terminal's scrollback buffer.

Scroll Navigation

When you scroll up in any terminal or agent panel to review earlier output, Canopy keeps track of whether new content has arrived since you left the bottom. Two features help you get back to where the action is.

"New output below" indicator. A floating pill appears at the bottom of the panel whenever you're scrolled back and new output arrives. The pill reads "New output below" with a down arrow. Click it to jump straight to the bottom and restore keyboard focus to the panel. The indicator stays out of the way of normal mouse interactions (drag-to-select, right-click menus) and animates in smoothly, respecting reduced motion preferences.

The indicator only appears when both conditions are true: you've scrolled away from the bottom, and new output has actually arrived. Scrolling up on its own won't trigger it. It also won't appear during full-screen programs like vim, less, or htop, since those take over the entire terminal buffer.

Scroll to Last Activity. This keyboard shortcut jumps the focused panel to the line where output was most recently written. It's different from scrolling to the very bottom: if your agent produced output 500 lines up and the prompt is at the end of the buffer, this shortcut takes you to the output, not the prompt.

You can also run this from the Command Palette (Cmd+Shift+P) by searching for "Scroll to Last Activity". Pressing the shortcut twice in a row gets you to the absolute bottom of the buffer, which is useful when the last activity position and the end of the buffer are close together. During full-screen programs (vim, less, htop), the shortcut falls back to a plain scroll-to-bottom since last-activity tracking pauses in alternate screen mode.

File Viewer

The File Viewer is a modal overlay that lets you inspect any file without leaving Canopy. When an agent references a file path in its output, you can click it to see the contents right there, with full syntax highlighting and diff support. No context switching to an external editor just to read a file.

Opening Files

There are two main ways to open the File Viewer:

• Click a file path in terminal output — Canopy automatically detects file paths in agent and terminal output, including path:line:col patterns like src/index.ts:42:7. Clicking a detected path opens the File Viewer.
• Click a changed file in the Review Hub or worktree sidebar — opens the File Viewer in Diff mode by default. See the Review Hub page for more on reviewing changes.

The modal header shows the branch name, relative directory, and filename. Hover over the title to see the full absolute path. An Open in Editor button sends the file to your external editor (configured in Settings > Integrations > External Editor) at the current line.

View Mode

View mode renders file content in a read-only editor with syntax highlighting. Language is detected automatically from the file extension, covering 40+ languages including JavaScript, TypeScript, Python, Rust, Go, and many more. When you open a file from a path:line link, the target line is highlighted and scrolled into view.

The editor includes:

• Line numbers in the gutter
• Code folding with clickable fold arrows next to collapsible blocks
• Metadata bar above the code showing line count, file size, and encoding (e.g. 142 lines · 4.2 KB · UTF-8)
• In-viewer search (Cmd+F) with highlighted matches
• Go-to-line (Cmd+L) for jumping to a specific line number

Diff Mode

When a git diff is available for the file, a View / Diff toggle appears in the header. Files opened from the Review Hub or worktree sidebar default to Diff mode. Files opened from a terminal link with a specific line number default to View mode. You can switch between modes freely.

Diff mode features:

• Split or Unified layout toggle for side-by-side or single-column diffs
• Diff stats in the file header showing additions and deletions
• Copy Diff button to copy the raw unified diff to clipboard

Image Preview

Image files (PNG, JPG, GIF, WebP, BMP, ICO) render inline in the modal instead of showing a binary file error. SVG files are sanitized and displayed as inline HTML. The header button changes to Open in Image Viewer, which opens the file in your system's default image viewer.

Keyboard Shortcuts

These shortcuts are active while the File Viewer is open:

Limits and Error States

The File Viewer enforces hard size limits that are not configurable:

Files that exceed these limits or cannot be displayed will show one of the following messages:

• Binary file — "Binary file — cannot display"
• Too large — "File too large to display" (the threshold matches the active mode: 500 KB in View, 1 MB in Diff)
• Not found — "File no longer exists"
• Outside project — "File is outside the project root"
• Invalid path — "Invalid file path"

In all error states, the Open in Editor button remains available as a fallback.

QuickRun

QuickRun is a collapsible panel at the bottom of the project sidebar, just below the worktree list. It gives you a fast way to fire off a terminal command or start a long-running process without setting up a full Recipe. The panel header reads "Run on {worktree-name}", reflecting whichever worktree is currently selected.

Running a Command

The input bar shows a $ prompt on the left. Type your command and press Enter to run it. The input clears automatically and the command is saved to your history.

While the suggestion dropdown is open, use Arrow Down and Arrow Up to navigate suggestions, and Escape to close it.

Output Location

A toggle button next to the input controls where the terminal panel appears:

• Grid (default) — opens in the main panel grid as an interactive terminal.
• Dock — runs in the dock (the minimized strip for background terminals) as a background task.

The button's tooltip shows the current mode, so you always know where the next command will land.

Command Suggestions

Focusing the input or typing opens a suggestion dropdown with three types of entries:

• Pinned commands — saved commands shown with a green pin icon and bold label. Hover to reveal the unpin button.
• Detected scripts — commands pulled from package.json (and similar), shown with a terminal icon.
• History — your last 10 commands, most recent first, with a clock icon. Duplicates are filtered out.

Filtering uses simple substring matching as you type.

Pinning Commands

Hover over any suggestion and click the pin icon to save it. At pin time, both the current auto-restart toggle state and output location are captured as the command's preferred settings.

When you run a pinned command, those saved preferences override the current toggle states. Both toggle buttons visually update to reflect the pinned command's settings.

Auto-Restart

The auto-restart toggle is the circular arrow button in the input bar. When enabled, it lights up in accent green with the tooltip "Auto-restart: On". The setting persists per-project, so you can leave it on for projects where you always want dev servers to come back after a crash.

When the toggle is on at the moment you launch a command, the spawned terminal is configured to restart automatically whenever its process exits. Here's what happens:

1. The process exits and Canopy checks the exit code and panel state.
2. An exponential backoff delay kicks in: starting at 250ms, doubling each attempt (500ms, 1s, 2s, 4s), capped at 5 seconds.
3. During the delay, a green spinner banner reading "Auto-restarting…" appears inside the terminal.
4. Once the delay passes, the command restarts. The normal "Session exited" banner is suppressed.

If the process ran for more than 10 seconds before exiting, the backoff resets to zero. A stable run followed by a crash is treated as a fresh event, not a continuation of a crash loop.

Active Tasks

Above the input bar, a task list shows up to 5 QuickRun-spawned panels for the active worktree. Each row displays a status indicator, the command (truncated to 28 characters), and elapsed time for running processes.

• Running — pulsing green dot. Hover for stop and focus actions.
• Restarting — pulsing amber dot, shown during the auto-restart backoff delay.
• Success — green dot. The row auto-dismisses after 3 seconds.
• Failed — red dot with a left border accent. Hover for restart (hidden when auto-restart is active), dismiss, and focus actions.

Click any row to focus that terminal panel. When more than 5 tasks exist, a "+ N more" label appears below the list.

Recipes

Save terminal configurations you use often as recipes for one-click launching. See the Recipes page for details.