Session Management

What Gets Persisted

Daintree 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 Daintree 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), Daintree 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 Daintree 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 Daintree 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

Daintree 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

Daintree manages the terminal-sessions/ directory (inside Daintree'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 removes its .restore file. For agent panels, this happens after the 20-second trash window closes, not immediately on close
• 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 DAINTREE_TERMINAL_SESSION_PERSISTENCE=0 before launching Daintree. This is a developer-facing escape hatch, not a regular setting.

Agent Session History

When you trash an agent panel, Daintree saves a session record after the trash window closes. The record lets you pick the conversation back up from the Panel Palette later. Records live in agent-session-history.json inside the app data directory.

The 20-second trash window

Closing an agent panel does not kill it straight away. The panel moves into the sidebar trash bin and starts a 20-second countdown. During the window you have three options:

• Restore — click the restore button on the trashed panel to bring it back exactly as it was. No session record is written.
• Remove now — click the X to kill the agent immediately and write the session record straight away.
• Let it expire — do nothing. After 20 seconds the PTY is killed and the session record is written.

Quitting Daintree with active agent panels writes their session records as part of shutdown, without waiting for a trash countdown. For the quit-confirmation dialog that protects in-progress work, see Session Resume on the agents page.

What gets saved

Each record captures enough metadata to relaunch the agent in the same state:

• Session ID from the agent's terminal output
• Agent type (Claude, Gemini, Codex, OpenCode)
• Model ID, if the agent reported one
• Worktree ID, so the record is scoped to where it was started
• Panel title — the last meaningful title emitted by the terminal, or the agent's default name if nothing useful was seen. Shell binary names, absolute paths, and prompt-style strings are filtered out so the label stays readable.
• Original launch flags (for example, --dangerously-skip-permissions for Claude) so resume keeps the same behavior
• Timestamp of when the record was saved

Resuming from the Panel Palette

Open the Panel Palette with Cmd/Ctrl+N and scroll to the Resume Sessions section at the bottom. Up to five entries are shown, scoped to the active worktree. Each entry reads Resume: {title} when a meaningful title was captured, or Resume {AgentName} otherwise. The subtitle shows the model, agent name, and a relative timestamp.

Selecting an entry launches a new agent panel with the correct resume flag and the original launch arguments. You get a fresh panel that continues the same conversation. For the per-agent resume syntax, see Agent Session Resume.

Storage limits

Up to 50 records are kept per worktree, newest first. Anything older than 30 days is pruned automatically on the next write. The history file is evicted along with the rest of Daintree's session data, so you should never need to clean it up manually.

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

• Daintree 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

Daintree hooks into your OS power management. When agents are actively working or running, Daintree 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.

Custom panel names survive project switches. If you rename a panel by double-clicking its tab title, or via the right-click context menu's Rename item, that name is restored when you return to the project. The custom name takes precedence over whatever title the terminal or agent would otherwise set.

Focus Mode

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