Settings

Open Settings with Cmd+, (macOS) or Ctrl+, (Windows/Linux), or click the gear icon in the toolbar. The dialog has a left sidebar with grouped tabs and a content panel on the right. A scope switcher in the sidebar header lets you toggle between Global and Project settings when a project is open.

Search

Press Cmd+F or / while the Settings dialog is focused to jump to the search field. Canopy uses fuzzy matching across all setting names, descriptions, and keywords, so partial matches and minor typos still surface the right results.

When you type a query, match count badges appear next to each tab in the sidebar showing how many results that tab contains. The content panel is replaced with a scrollable list of result cards, each showing a breadcrumb path (Tab > Subtab > Section), the setting title with highlighted matches, and a description. Use the arrow keys to move through results and Enter to navigate directly to that setting's tab.

Press Esc to clear the query. A second Esc blurs the search field entirely.

The @modified filter

Type @modified (or @mod for short) in the search box to show only settings that differ from their defaults. You can combine it with keywords too: scrollback @modified filters to modified scrollback-related settings specifically.

If no settings have been changed, the results area shows an empty state confirming everything is at its default value.

Global settings

Global settings are organized across 16 tabs in four sidebar groups: General, Terminal, Integrations, and Support. These apply to Canopy as a whole, regardless of which project is open.

General group

General

The General tab has three subtabs: Overview, Hibernation, and Display.

Overview shows the current Canopy version, a system status panel listing each agent CLI (Claude, Gemini, Codex, OpenCode) with its detection status, the update channel selector (Stable or Nightly), and a collapsible Quick Reference card with essential keyboard shortcuts. Clicking an agent in the system status list navigates directly to that agent's settings.

Hibernation controls auto-hibernation for background projects. When enabled, projects you haven't interacted with are paused after the threshold you choose: 12, 24 (default), 48, or 72 hours. Auto-hibernation is off by default.

Display contains four toggles that control visual indicators across the app:

• Project Pulse (on by default) shows a commit activity heatmap on the empty panel grid
• Developer Tools (off by default) adds a problems panel button to the toolbar
• Grid Panel Agent Highlights (off by default) shows colored borders on grid panels when agents are waiting or working. Failed state borders are always visible regardless of this setting.
• Dock Item Agent Highlights (off by default) shows colored borders on dock items when agents are waiting. Failed state borders are always visible regardless of this setting.

Appearance

The Appearance tab has two subtabs: App and Terminal.

The App subtab contains the theme picker with 14 built-in themes, a color vision accessibility selector (Default, Red-Green for Deuteranopia/Protanopia, or Blue-Yellow for Tritanopia), and a Dock Density selector (Compact, Normal, or Comfortable). For details on themes, auto-switching, and sharing, see Theme System.

The Terminal subtab controls:

• Terminal Color Scheme for ANSI color palettes. See Terminal Color Schemes.
• Font Size (8 to 24px)
• Font Family (JetBrains Mono bundled by default, or System monospace)

Keyboard

View, search, and rebind all keyboard shortcuts. Click any shortcut to record a new binding, with conflict detection warning you if the combination is already in use. Import and export shortcut profiles as JSON files, or reset individual shortcuts (or all at once) to their defaults.

See Keyboard Shortcuts for the full reference and profile system.

Notifications

Configure notification delivery, agent event triggers, and the sound system. See Notifications & Sound for full documentation.

Privacy & Data

The Privacy & Data tab has two subtabs: Telemetry and Data & Storage.

Telemetry offers three levels:

• Off collects and sends nothing, including crash reports
• Errors Only sends crash reports and error details, but no usage analytics
• Full Usage sends crash reports plus anonymous usage analytics

Data & Storage provides:

• Data Folder shows the path to Canopy's data directory with an "Open Folder" button
• Log Retention controls how long log files are kept: 7 days, 30 days (default), 90 days, or Keep forever. Pruning runs at startup.
• Clear Cache removes HTTP and code caches without affecting your settings
• Reset All App Data permanently deletes all settings, API keys, session data, and logs

Terminal group

Panel Grid

The Panel Grid tab has five subtabs: Performance, Input, Layout, Scrollback, and Accessibility.

Performance contains:

• Performance Mode reduces scrollback to a fixed low value and disables animations. Useful on lower-end hardware.
• Resource Monitoring shows CPU and memory usage in panel headers, polling every 2.5 seconds
• Memory Leak Detection watches for runaway memory growth and can auto-restart affected terminals when they exceed a configurable threshold (1,024 to 32,768 MB). Requires Resource Monitoring to be enabled.
• Panel Limits sets thresholds for how many panels you can open simultaneously. Defaults are auto-detected from your hardware (RAM and CPU cores). Three levels are configurable: a soft warning banner, a confirmation dialog, and a hard limit that cannot be bypassed. You can disable the warning and confirmation prompts, but the hard limit always applies.
• Cached Project Views controls how many projects are kept in memory for instant switching (1 to 5, default 1). Switching to an evicted project takes roughly 500ms to reload.

Input controls the Hybrid Input Bar, a multi-line text input that appears above agent terminals:

• Hybrid Input Bar (on by default) enables or disables the input bar across all agent panels
• Auto-Focus Input (on by default, nested under Hybrid Input Bar) determines whether selecting a panel focuses the input bar or the terminal directly

Layout controls panel arrangement:

• Two-Pane Split Layout (on by default) displays a resizable side-by-side view when exactly two panels are open. The split ratio is remembered per worktree.
  • Preview-Focused Layout uses a 65/35 split favoring browser or dev preview panels, instead of a balanced 50/50
  • Default Ratio slider sets the initial split (20% to 80%)
  • Reset All Worktree Split Ratios reverts all saved ratios to the default
• Grid Layout Strategy determines how panels beyond two are arranged:
  • Automatic (default) adapts columns based on panel count
  • Fixed Columns scrolls vertically with a set column count (1 to 10)
  • Fixed Rows expands horizontally with a set row count (1 to 10)

Scrollback sets the terminal history buffer size:

• 500 lines (Minimal)
• 1,000 lines (Default)
• 2,500 lines (Extended)
• 5,000 lines (Full history)

Agent terminals receive 1.5× the base scrollback limit (up to 5,000 lines). Shell and dev server terminals use a reduced 0.3× multiplier (up to 2,000 lines). An expandable section shows estimated memory usage per terminal type and total. See Scroll Buffer Limits for the full breakdown.

Accessibility provides Screen Reader Mode with three options:

• Auto (default) follows your operating system's accessibility setting
• On always enables screen reader support
• Off disables screen reader support

When enabled, Screen Reader Mode adds an accessible DOM overlay to terminals. This has a performance cost, which is why it defaults to following the OS rather than being always on.

Worktree

Configure the directory pattern for new worktrees using template variables like {base-folder}, {branch-slug}, {repo-name}, and {parent-dir}. Three presets are available (Sibling Folder, Subdirectory, Flat Sibling), and a live preview shows the resolved path with sample data.

See Projects for details on path patterns and variables.

Toolbar

Customize the toolbar layout by dragging buttons to reorder them and toggling visibility for each one. The Launcher Palette section controls the default panel type and whether the dev server option is always visible in the panel launcher palette. A reset button restores the default toolbar layout.

See UI Layout for more on toolbar customization.

Environment

Define per-project KEY=VALUE pairs that Canopy injects into every new terminal session spawned within that project. This gives each project an isolated environment without touching your shell configuration or .env files. Useful for project-specific API endpoints, feature flags, tool configuration, or any value your agents and terminals need at runtime.

Environment variables are scoped to the project, not individual worktrees. All worktrees within a project share the same set of variables. These values are stored locally on your machine and are never written to .canopy/ files or committed to your repository, so each team member needs to configure them separately. See Projects for more on project scope.

• Add Variable — appends an empty row with key and value fields
• Key field — monospace input for the variable name (validated on save)
• Value field — input for the variable value; masked for sensitive keys
• Delete — remove a row with the trash icon
• Save / Discard — changes are not live until you explicitly save. Discard rolls back to the last saved state.

If no project is open, the tab shows an empty state prompting you to open one first.

Sensitive Variables

Canopy automatically detects sensitive variable names. Any key containing KEY, SECRET, TOKEN, or PASSWORD (case-insensitive) is treated as sensitive.

• Masked display — values are hidden by default with an eye toggle to reveal them
• Lock icon — a green lock indicates the variable is stored in secure storage; an amber shield icon means it is still in plaintext and needs migration
• Separate storage — sensitive values are stored in electron-store, separate from the plaintext settings.json file

Validation Rules

Variable names must start with a letter or underscore and contain only letters, digits, and underscores. Invalid names show an inline error when you save. Duplicate names are also flagged. Empty key rows are silently ignored.

Plaintext Migration Warning

If Canopy detects sensitive variables stored in plaintext (from an older version), an amber warning banner lists the affected key names. Clicking Save automatically migrates them to secure storage. No manual action is needed beyond saving.

Terminal Injection

Variables are injected at PTY spawn time. This covers initial terminal creation, terminal restarts, and terminal type conversions. Your project variables bypass the built-in terminal security filter (described below), so they are always injected regardless of the key name.

Terminal Security Filter

Separately from project environment variables, Canopy filters the inherited shell environment before spawning any terminal process. This prevents credentials from your shell leaking into agent and terminal sessions.

The filter strips variables that match a built-in blocklist of common credential names (such as ANTHROPIC_API_KEY, DATABASE_URL, GITHUB_TOKEN, AWS_SECRET_ACCESS_KEY, and others) as well as any variable whose name contains credential-related keywords like SECRET, PASSWORD, TOKEN, PRIVATE_KEY, or CREDENTIAL at word boundaries.

The filter is hardcoded and not user-configurable. Variables from the CANOPY_* namespace are always stripped from inheritance and re-injected fresh by Canopy itself. Your project-configured environment variables bypass this filter entirely, since they represent intentional configuration rather than inherited credentials.

Integrations group

CLI Agents

The CLI Agents tab has a General subtab plus one subtab per agent (Claude, Gemini, Codex, OpenCode, Cursor).

The General subtab contains:

• Default Agent sets which agent is used for the Help dock button (Cmd+Shift+H) and automated workflows like "What's Next?" and onboarding. When set to "None," Canopy picks the first available agent. This is separate from the Portal's default new tab agent.
• Run Setup Wizard re-runs the initial agent configuration flow

Each per-agent subtab provides:

• Enable Agent (on by default) controls whether the agent appears in the UI. Disabled agents are hidden everywhere and treated as if not installed.
• Custom Arguments for extra CLI flags passed to the agent on every launch
• Help Output (expandable) shows the agent's CLI help text
• Installation guidance when the CLI is not detected, with copy-able install commands and a re-check button

External Editor

Canopy can open files at a specific line and column in your preferred code editor. This preference is saved per-project, so each project remembers its own editor choice.

Eight built-in editors are supported:

• VS Code
• VS Code Insiders
• Cursor
• Windsurf
• Zed
• Neovim
• WebStorm / IntelliJ
• Sublime Text

A ninth option, Custom, lets you configure any editor (see below). Editors that cannot be located on your system show a (not found) suffix in the dropdown.

Editor discovery

Canopy scans your PATH and editor-specific directories automatically when the settings panel opens. Below the dropdown, a detected editors list shows each editor's status with a checkmark or warning icon, along with the resolved executable path.

The Rescan button (circular arrow icon next to the dropdown) re-runs discovery on demand without restarting the app.

On macOS, Canopy also probes /Applications and ~/Applications for editor .app bundles. This handles editors installed via their GUI installer without the "Install Shell Command" step. GUI applications on macOS inherit a minimal system PATH rather than your shell configuration, so an editor that works fine from your terminal might still appear as (not found) in Canopy. The .app bundle detection works around this automatically for VS Code, Cursor, Windsurf, Sublime Text, and JetBrains IDEs.

Custom editor

When you select Custom from the dropdown, two additional fields appear:

• Command — the executable name or full path (e.g. code, nvim, subl)
• Arguments template — command-line arguments using {file}, {line}, and {col} as placeholders. The default template is {file}:{line}:{col}.

Canopy expands the placeholders at launch time. If your file paths contain spaces, make sure to quote the {file} placeholder in the template.

Save and Test

• Save — persists the editor choice to the current project. The button shows confirmation text with the editor name on success, or an error message if something goes wrong.
• Test — opens your home directory in the configured editor to verify it launches. Shows a success or failure badge inline. Note this only confirms the editor starts; it does not validate that your arguments template correctly passes line and column values.

Where Canopy opens files

Three surfaces use the configured editor:

• Terminal output — Cmd+click (macOS) or Ctrl+click (Windows/Linux) on a detected file path. A plain click opens the in-app file viewer instead. See Terminals & Panels.
• File Viewer (diff mode) — clicking a file row in the Review Hub opens it in the in-app File Viewer. The Open in Editor button in the File Viewer header then opens the file at the first changed line. See Review Hub.
• File viewer — the Open in Editor button in the file viewer modal header.

If the configured editor is unavailable, Canopy falls back through $VISUAL/$EDITOR environment variables, then any detected known editor, then the platform-native open command (macOS only), and finally a last-resort shell open. Line and column targeting is only preserved when a supported editor handles the request.

Image Viewer

The Image Viewer setting controls which application Canopy uses to open image files. It defaults to the OS viewer (Preview on macOS, the default image app on Windows and Linux). Select Custom to provide your own command, using {file} as the path placeholder.

Like External Editor, Image Viewer is a per-project preference, so the panel requires a project to be open before you can configure it.

Speech-to-Text (Voice Input)

Enable voice dictation with a Deepgram API key. Configure your language, transcription model, paragraph break strategy, and custom dictionary. See Voice Input for full documentation.

AI Text Correction

Enable AI-powered correction of voice transcriptions using an OpenAI API key. Choose a correction model, toggle file reference resolution, and add custom correction instructions. See Voice Input > AI Text Correction for details.

Some settings are agent-specific:

• Inline Mode (Claude only) disables the fullscreen TUI for better resize handling and scrollback
• Share Clipboard Directory (Gemini only) lets the agent read pasted clipboard images

See AI Agents for details on agent configuration and capabilities.

GitHub

Enter your GitHub Personal Access Token (required scopes: repo, read:org). Use the Validate button to confirm the token works, or Clear to remove it.

See GitHub Integration for setup details.

Voice Input

Configure speech-to-text dictation and optional AI-powered text correction.

The Speech-to-Text section includes:

• Enable/disable toggle for the voice input system
• Microphone permission status with platform-specific instructions for granting access
• Deepgram API Key with validation on save
• Language (English, Spanish, French, German, Japanese, Chinese, Korean, Portuguese, Italian, Russian)
• Transcription Model (Nova-3 for best accuracy, Nova-2 as a stable fallback)
• Paragraph Breaks (spoken commands like "new paragraph," or manual Enter only). Spoken commands require English; non-English languages automatically fall back to manual mode.
• Custom Dictionary for domain-specific terms (up to 100) to boost recognition accuracy

The AI Text Correction section (visible when Voice Input is enabled) post-processes transcriptions to fix technical terms, punctuation, and filler words:

• OpenAI API Key with validation on save
• Correction Model (GPT-5 Mini for higher quality, GPT-5 Nano for speed)
• Resolve File References converts voice commands like "link to the input component" into @file references
• Custom Instructions for project-specific correction rules
• Inspect Core Prompt (expandable) shows the base correction prompt

See Voice Input for the full guide.

Portal

Configure the Portal panel's default new tab agent, system-provided default links, and your own custom links.

MCP Server

The MCP Server tab controls a local server that lets external AI agents invoke Canopy actions.

• Enable/disable toggle starts or stops the server immediately
• Copy MCP Config copies a ready-to-paste JSON configuration snippet for your MCP client
• Server Port sets a fixed port. Defaults to 45454; if that port is taken, Canopy automatically tries the next available port (45455, 45456, and so on).
• API Key Authentication generates a bearer token for securing external connections

See AI Agents > MCP Server for setup and usage details.

Support group

Troubleshooting

Diagnostic and recovery tools for when things go wrong:

• Hardware Acceleration lets you disable GPU acceleration if you see blank panels or rendering artifacts
• System Health Check verifies that Git, Node.js, and npm are accessible
• Application Logs provides buttons to open the log file and clear accumulated entries
• Developer Mode enables verbose logging, auto-opens the diagnostics dock, and focuses the Events tab on open. Each of these is independently toggleable as a sub-setting.

See Troubleshooting for common issues and recovery steps.

Automatic Resource Management

Adaptive Resource Profiles

Canopy evaluates three system signals every 30 seconds: total private memory usage, whether you're running on battery power, and how many worktrees are open. These signals produce a pressure score that selects one of three internal profiles: Performance, Balanced, or Efficiency.

The Balanced profile matches Canopy's standard behavior. Performance mode speeds up polling and allows more WebGL contexts for terminal rendering. Efficiency mode slows down background polling and hibernates idle projects more aggressively (after 15 minutes of inactivity instead of 30). This internal hibernation is distinct from the user-configured Auto-hibernation in Settings > General, which operates on a separate timer measured in hours and is not triggered by memory pressure.

Profile transitions are rate-limited to avoid oscillation. Upgrading to a less restrictive profile requires 60 seconds of sustained lower pressure. Downgrading to a more restrictive profile requires 30 seconds of sustained higher pressure. There is no indicator in the UI showing which profile is active.

Memory Pressure Mitigation

Separately from resource profiles, Canopy monitors per-process memory and responds in two escalating tiers when individual processes exceed their thresholds.

Tier 1 fires immediately when memory pressure is detected. Canopy clears internal caches, releases hidden webviews, and trims terminal state. Tier 2 fires after three consecutive pressure intervals and hibernates idle projects. A 10-minute cooldown prevents repeated hibernation of the same projects.

Disk Space Monitoring

Canopy monitors the application data volume (not necessarily your system drive) every 5 minutes. Two thresholds trigger notifications:

• Warning (below 500 MB) — a toast notification appears for 8 seconds. If Canopy is not focused, a native OS notification is sent as well.
• Critical (below 100 MB) — a persistent toast stays visible until you free space. Session backups and terminal snapshots are paused automatically to stop consuming disk. They resume once space is available.

Notification cooldown is 30 minutes to avoid repeated alerts, though a transition from warning to critical always notifies immediately. For troubleshooting steps, see Troubleshooting.

Sleep Prevention

While any agent is actively running, Canopy prevents the system from suspending the app. This keeps CPU and network active so long-running agent tasks complete without interruption. The display can still dim or turn off normally.

Sleep prevention releases automatically when all agents finish. A 4-hour safety cap ensures the blocker is released even if agent state tracking encounters an issue.

PTY Host Resource Governor

The terminal host process has its own resource guard. If the PTY host heap exceeds 85% of its limit, all terminal output is temporarily throttled. Output resumes when the heap drops below 60% or after 10 seconds, whichever comes first. You may notice a brief pause in terminal output during high-volume bursts. This is expected behavior, not a bug.

Project settings

Project settings let you override global defaults on a per-project basis. To access them, open the scope switcher dropdown in the sidebar header and select Project. This option only appears when a project is open.

General (project)

Set the project display name, emoji, color, and custom SVG icon. Configure the dev server URL and load timeout. Enable or disable in-repo settings, which writes project configuration to a .canopy/ directory in the project root (specifically .canopy/project.json and .canopy/settings.json).

Context

Control what content is included when Canopy builds context from your project:

• Excluded Paths using gitignore-style patterns
• Copy Tree Settings for context size limits, file size limits, and include/exclude patterns
• Environment Variables at the project level

Worktree Setup

Configure what happens when a new worktree is created for this project:

• Run Commands executed in terminals on worktree creation
• Default Worktree Recipe applied to new worktrees
• Branch Prefix (none, username, or custom prefix)
• Worktree Path Pattern overrides the global pattern for this project
• Terminal settings for shell, shell arguments, working directory, and scrollback

See Worktrees for more on worktree configuration.

Recipes

Create, edit, and delete terminal recipes scoped to this project. See Recipes for the full guide.

Commands

Define project-specific /slash command overrides and aliases that layer on top of global commands. See Unified Input for details on the command system.

Notifications (project)

Override global notification settings on a per-project basis. Project overrides layer on top of global settings, so you can silence noisy projects or add extra alerts for critical ones.

See Notifications & Sound for the notification system reference.

GitHub (project)

Select which git remote Canopy should use for GitHub integration in this project. Useful for repos with multiple remotes where the default origin is not the one you want for issues, PRs, and pulse data.

Modified indicators

A small green dot appears on a tab's icon in the sidebar when any of that tab's settings differ from their defaults. This gives you a quick visual scan of which areas you've customized.

Three tabs currently track modified state:

The indicator helps you find settings you've changed, especially when combined with the @modified search filter for a full list of non-default values.