Session Management

What Gets Persisted

Canopy saves and restores your workspace state automatically across sessions:

Terminal State

• Scroll buffer — terminal content is serialized to disk so you can see previous output after a restart. See Scroll Buffer Limits for details on how much history is kept.
• Panel arrangement — which panels are open, their positions in the grid, and their sizes
• Active worktree — which worktree was selected
• Focus state — which terminal had focus in each worktree

Each terminal's scroll buffer is serialized using xterm's built-in serializer and written to a .restore file on disk. Snapshots are debounced, so Canopy waits five seconds after terminal output settles before writing. Terminals with fewer than 1,000 lines are serialized synchronously. Larger buffers use an async path that yields to the event loop, keeping the PTY host responsive during active agent runs.

When a project is reopened or you switch back to it, each terminal's .restore file is replayed into the terminal. You'll see a dim separator line at the top of the restored content:

• ─── Session restored · <date and time> ─── for a normal restore
• ─── Session hibernated · <date and time> · auto-suspended to save resources ─── if the project was hibernated (no scroll content is restored in this case, just the banner)
• ─── Restored · <date and time> · previous session was in a full-screen app ─── if the terminal was running a full-screen app like vim or htop

For large buffers (over 256 KB of serialized data), Canopy restores content incrementally in 32 KB chunks with yields between each chunk. This keeps the UI responsive while the scroll history streams in. Your scroll position from the previous session is preserved after the restore completes.

App State

• Sidebar width — your custom sidebar size
• Window bounds — position, size, and maximized/fullscreen state
• Portal state — tabs, links, default target, and width
• Terminal sizes — per-panel resize ratios
• Focus mode — whether focus mode was active

For resuming agent conversations (as opposed to workspace state), see Agent Session Resume.

This persistence applies to clean restarts and project switches. If Canopy detects a crash loop on startup, it boots in safe mode and intentionally skips panel restoration to break the loop. This is temporary — the crash counter resets after five minutes of stable running. For more on how Canopy handles unclean exits, see Crash Recovery.

Scroll Buffer Limits

Scrollback line limits

The scrollback setting controls how many lines of history each terminal keeps in memory. This is also the upper bound on what gets serialized to disk. The base value is configured in Settings > Terminal (Scrollback section) with presets of 500, 1,000 (default), 2,500, and 5,000 lines.

Different terminal types apply multipliers to the base setting, because agent run logs are typically more valuable to keep than shell command output:

At the default base of 1,000 lines, agent terminals keep up to 1,500 lines and standard terminals keep up to 300 lines. If you need more history, bump the base setting to 2,500 or 5,000 in Settings.

Serialization size cap

Canopy keeps up to 5 MB of serialized scroll buffer per terminal. At roughly 250 bytes per line (including ANSI colour codes), 5 MB fits around 20,000 lines, well above the 5,000-line maximum that any terminal type can hold. In practice, this cap is rarely reached.

The one scenario where it can matter is terminals with unusually dense ANSI output, such as heavily colour-coded diffs or verbose logging with escape sequences. These can push the per-line byte count well above 250 bytes, bringing a 5,000-line agent buffer closer to the 5 MB threshold.

Storage and Eviction

Canopy manages the terminal-sessions/ directory (inside Canopy's app data directory) automatically. There's no manual cleanup needed:

• 30-day TTL — session files older than 30 days are deleted on startup
• 100 MB total cap — if the directory exceeds 100 MB, the oldest files are evicted first
• Orphan cleanup — files for terminals that no longer exist are removed on startup
• Panel removal — deleting a terminal panel immediately removes its .restore file
• Hibernation — hibernating a project clears its session files. When the project is next opened, terminals start fresh with a "Session hibernated" banner instead of restored scroll content

Disabling persistence

To disable terminal session persistence entirely, set the environment variable CANOPY_TERMINAL_SESSION_PERSISTENCE=0 before launching Canopy. This is a developer-facing escape hatch, not a regular setting.

Hibernation

Hibernation pauses background projects to free up system resources. When a project is hibernated:

1. All PTY processes for the project are killed
2. Its persisted state file is cleared
3. It stays in the project list but starts fresh when reopened

Configuration

Configure hibernation in Settings > General:

• Enable/disable — off by default
• Threshold — how long a project must be idle before hibernating: 12, 24 (default), 48, or 72 hours. Configurable between 1 and 168 hours.

How It Works

• Canopy checks for hibernation candidates every hour (first check runs 5 seconds after startup)
• The active project is never hibernated — only background projects qualify
• When you switch back to a hibernated project, just relaunch the terminals you need

System Sleep & Wake

Canopy hooks into your OS power management. When agents are actively working or running, Canopy prevents the system from sleeping automatically. If sleep does occur (for example, you close your laptop lid), the following applies:

On Sleep

• PTY processes are paused
• Background projects may be hibernated
• Sleep metrics are recorded

On Wake

• PTY processes are resumed
• Worktree state refreshes (picks up any external changes)

Project Switching

When you switch between projects:

1. The current project's state is saved (terminal layout, active worktree, panel sizes)
2. The UI tears down and rebuilds for the new project
3. The new project's state is restored from its last saved state
4. Worktrees and terminals load for the new project

The previous project can continue running in the background or be fully closed, depending on your choice in the close dialog.

Focus Mode

Focus mode is a per-project toggle that strips away UI chrome for a distraction-free view. The state persists across sessions.