Project Memory
How Daintree caches and restores project views, sleeps a project, closes idle views, reports memory pressure, and handles system sleep and wake.
Project-level session state
Switching projects saves the outgoing project's state (terminal layout, active worktree, panel sizes) and swaps in the incoming one. What that swap feels like depends entirely on whether the target project's renderer is still warm.
Warm and cold
Daintree keeps a small number of recently used project views alive in memory. The number scales with your machine's RAM, because a warm view is only worth holding if there is room for it:
| System memory | Cached views |
|---|---|
| 64 GB or more | 5 |
| 32 GB or more | 4 |
| 16 GB or more | 3 |
| Below 16 GB | 2 |
The cap counts the active view, so a cap of 4 means three warm background projects. It can be set explicitly, from 1 to 5, at Settings > Terminal > Performance > Project views > Cached project views; see Cached project views.
- A warm switch re-attaches a view that is already built. It avoids a renderer boot, and focus returns to the terminal you left.
- A cold switch starts a renderer and rebuilds the project UI. How long it takes and how much memory it uses depend on the project and machine.
The skeleton
A cold switch used to mean staring at the old project for the whole boot. The outgoing view now detaches as soon as the incoming one paints a themed skeleton, before React mounts. The incoming project shows its loading surface while the rest of its UI boots. The skeleton is opaque over the view's own themed background, so there is still no blank frame anywhere in the transition.
Switches are serialized: clicking through several projects quickly queues them in order rather than racing. A cold start that stalls doesn't hang the UI. The paint gate has a soft and a hard budget, both scaled by the active resource profile. Past the soft budget the outgoing project simply stays on screen while the slow view keeps loading. A view that still hasn't painted at the hard budget is abandoned: the switch is rolled back, you stay in the project you were in, and a Couldn't switch project toast says the project didn't finish displaying and offers Try again.
Hover prefetch
While the project switcher is open, hovering a row primes that project before you click. Daintree waits 150 ms after the pointer settles, then reads that project's saved state from disk (app state, terminal snapshots, panel layout, active worktree, focus mode, terminal config, agent settings), so it's in memory by the time you select it.
Prefetch is mouse-only; touch and pen pointers are ignored, as are the active project and any project flagged missing. The primed state is cached for 30 seconds and consumed once, on the click that follows; the renderer's own freshness gate skips a re-read within 15 seconds of a successful prime.
Eviction and freeze
When a project's view leaves the warm cache, it goes one of two ways:
- Eviction destroys the Chromium renderer and releases its memory. Returning to that project pays a cold rebuild.
- Freeze keeps the view in memory but suspends it: timers and the event loop paused through the page lifecycle API. It still costs RAM and resumes without a renderer boot.
Which one happens depends on why Daintree is under pressure. Only memory pressure that actually contributed to the resource profile destroys views; when the efficiency profile engages for other reasons (battery, thermal, sustained CPU), views are frozen instead, so they return the moment the pressure lifts. Freeze entry is debounced on the trailing edge, so a quick glance at another project doesn't freeze the one you just left; freeze exit is immediate.
Eviction under memory pressure steps down rather than falling off a cliff. Above the warning threshold your configured cap stands; below the critical threshold the cache collapses to the active view alone; between them the cap drops by one view per equal slice of the band, so warm switching degrades gradually instead of vanishing in a single pass. On macOS, a kernel memory-pressure warning sustained alongside heavy swap use counts as critical too. Within a pass, eviction is least-recently-used inside a fixed order: idle views first, then views with an active agent, then views an MCP session is bound to, then projects set to Keep workspace resident. A view running a Daintree Assistant session is never evicted. What gets evicted has the reasons for each tier.
Sleep project
Sleep project, in a project's context menu in the project switcher, puts one project to sleep the way quitting puts them all to sleep, without losing your place in it. It tears down all three reclaimable tiers: a graceful, session-preserving kill of the project's PTYs, its cached renderer views, and the workspace host process. Session ids are written back into the saved panel snapshots and journaled, hibernation markers are written so scrollback replays with an explanatory banner, the Assistant's own session is captured for resume, the project's plugins are unloaded, and the layout is left alone.
Use the project dropdown in the toolbar for this action: click the project name, then right-click its row and choose Sleep project. In the current release, the full project switcher can close before showing the confirmation.
It is offered for any project that is open and not missing, including the one on screen; an already-sleeping project has nothing to reclaim, so it isn't offered there. Sleeping the project on screen drops its window to the project picker. A project with running processes or agents, or the one on screen, asks first: the Sleep '<project>'? dialog lists what will be stopped under "Running processes will be stopped" and promises that "The layout, terminal scrollback, and agent sessions come back when you reopen the project." A background project with nothing running sleeps at once.
The project stays in the switcher as closed. When it has agents to bring back, its row draws a solid gray dot (read aloud as "N agents will resume"), and reopening it restores the panels and attempts conversation resume through the supported session-ID integration. ID-less rolling-history and directory-scoped modes are not invoked automatically; those panels need the CLI's manual continuation command unless you supplied it in their launch arguments. If Daintree can't confirm the terminals stopped, it leaves the project open rather than hide work that may still be running, and offers Try again.
Auto-close idle projects
The same reclaim can run on a timer. Settings > General > Hibernation > Close idle projects automatically closes background projects that have been idle past a threshold, and it is the thing that actually reclaims memory over a long session.
- Off by default. It changes project lifecycle, so it is opt-in.
- Close after: 15 minutes (default), 30 minutes, 1 hour, or 2 hours.
- Swept every 5 minutes, with a quiet period after startup and after waking from sleep so it doesn't fire into a machine that is still settling.
- Gated on zero terminals. Any live terminal at all means the project is skipped: the sweep never destroys agent scrollback silently.
- Never the foreground project, in any window. The check reads every window's active project, not just the last-focused one.
Closed projects stay in the switcher, their rows reading Suspended to free memory, and reopen where you left them. Each one also leaves a low-priority Project suspended entry in the notification inbox.
Hibernate inactive projects and Hibernate after still appear in this settings section. Automatic process hibernation is disabled in the current implementation, so changing that toggle does not stop background terminals. Use Sleep project when you want to stop them deliberately.
Idle terminal reminders
Auto-close never touches a project with a live terminal. For those, Daintree can remind you instead: Notify me about idle terminals, in the same Background projects section, is on by default. When every terminal in a background project has been quiet past the Remind after threshold (1 hour by default; 30m, 1h, 2h or 4h) and no agent in it is working, an inbox entry reads Idle terminals in "<project>". Nothing closes on its own. Close them stops that project's terminals and frees its cached view; Mute project silences the reminder for the threshold or an hour, whichever is longer.
The memory notice
When the machine itself is short of memory for several minutes running, a quiet row appears at the top of the sidebar footer stating only what was measured, for example "macOS reports memory pressure at its warning level and swap is 85% full." The readings are the kernel's memory-pressure level on macOS, swap (or, on Windows, committed memory) at 80% or more, and an fseventsd process using 8 GB or more. The row clears itself once readings recover, and names no cause, because the pressure is often outside Daintree.
Its Memory actions menu offers two things:
- Ask agent about memory launches your default agent with a read-only prompt to find what is using the memory. It is told not to quit, kill or change anything without asking.
- Sleep idle projects appears when there are background projects with no agent mid-task (a waiting agent counts as idle). It lists them by name in a Sleep N idle projects? confirmation, warns that their terminals will be stopped, and then sleeps each one in turn exactly as Sleep project does. A project that comes on screen or starts working before its turn is skipped.
System sleep and wake
Daintree hooks into your OS power management. While agents are actively working, it holds off idle sleep; the display can still turn off. That is Settings > General > Overview > Keep awake > Keep awake while agents work, on by default, with Keep awake on battery beneath it, off by default, so an unplugged laptop can still sleep. When the system sleeps anyway (you close the lid), Daintree pauses PTYs, pauses workspace polling, and pauses its own main-process watchdog. That last one matters: without it, a long sleep would bank enough missed heartbeats for the watchdog to conclude the main process was hung and kill it on wake.
On wake, Daintree waits two seconds before doing anything, then re-arms the watchdog first, resumes PTYs, and resumes worktree status polling at the pace the current power state allows. The fuller refresh that picks up anything that changed outside the app (including network fetches) waits until a Daintree window is focused and visible on an unlocked screen: a machine that wakes overnight while you're away stays quiet until you come back to it. A forge token health probe is forced immediately, so a credential that expired during a long sleep is caught then rather than at the next scheduled probe.
The same power state shapes background work the rest of the time. Daintree combines battery, window focus, window visibility and the lock screen into one policy: background polling slows on battery or when no Daintree window has focus, and slows further when the screen is locked or no window is visible.
A window on a remote host works differently, because its terminals and agents run on the host, not on the machine that went to sleep. The host keeps them running while your laptop is closed. On wake, the window reconnects on its own and each terminal catches up on what it printed in the meantime. The host itself has to stay awake for that; see When the Connection Drops and Keep It Serving.