Skip to main content

The Project Switcher

How Daintree ranks and bands workspaces, reads their activity, moves or reattaches a project folder, and manages memory when you switch away.

Updated
Reviewed

Opening the switcher

Use the switcher to find a project or scratch workspace and move to it. Click the project button in the toolbar for the anchored dropdown, or press Option-Command-P Control-Alt-P Control-Alt-P for the wider modal.

Both forms make every registered workspace searchable; folded browse bands can hide their rows until expanded. The search box is labeled Search workspaces… and the list is a single listbox named Workspaces, because what you are searching now includes scratch workspaces alongside projects.

The toolbar button itself carries a badge dot when something outside the current project is active. The dot takes the waiting color when any background project has an agent waiting for input, and the working color when background agents are only working. Its accessible label states both facts, counting waiting by project (the question is "how many places need me?") and work by agent: 2 projects waiting for input, 3 background agents working.

Projects and scratch workspaces share one searchable switcher

The seven bands

Browsing the switcher (that is, with the search box empty) groups workspaces into seven bands in a fixed order. The order is the point: actionable work first, then explicit intent, then non-actionable system activity, then habit.

BandWhat lands hereOrder within it
Current projectThe project this window is showing.One row.
Needs attentionAgents blocked, waiting on input, or finished and not yet reviewed.Severity tier (blocked, then waiting, then ready-for-review) and oldest first inside each.
PinnedProjects you pinned.Alphabetical.
RunningLive agents, with nothing asking for you.Most agents first, then the freshest transition into working.
SnoozedAgents you deliberately quieted, and nothing else running.Frecency.
Other projectsEverything else, the residual catch-all.Whatever you picked; see Sorting.
UnavailableProjects whose directory is no longer at the stored path.Alphabetical.

Two of those placements are deliberate and worth stating outright. Pinned sits above Running: an explicit pin is a stronger signal than the operational fact that something is executing, so a pinned project with a running agent stays in Pinned: its status line still says 1 agent running. And Running requires live agents; a project holding only leftover processes falls through to Pinned or Other, where its status line says 1 process running.

Snoozed is its own band rather than a line inside Other, because the two mean opposite things. Other is the residual nothing-is-happening set; a snoozed project has live agents you chose to quiet. Sorting them together is what made a project with three snoozed agents read as dormant.

Empty bands are skipped. Browse headers with a chevron can fold their rows, and that preference is remembered. A folded header shows how many workspaces it contains. Searching ignores those folds and produces one ranked list, so a collapsed band cannot hide a matching project.

Note

The bands are a view over one flat array: the same array the arrow keys walk. There is never a second, narrower list underneath, which is what keeps the keyboard cursor and the row Enter commits to from drifting apart.

What a row says

Each row shows a leading mark, the project's emoji, its name, and one status line. That line answers two questions and keeps them apart: what this workspace wants from you, and whether anything in it is still executing. Answering both with one status was the old failure: a project with one agent still working and one waiting on you picked the wait out of a priority order and read like a project where everything had stopped.

The line is assembled left to right out of whichever of these the row has earned, separated by ·:

FragmentWhat it reads
Running count1 agent running / 4 agents running, or Assistant working where the machine's own session is the only thing executing. Absent when nothing is running, and the absence is half the signal: a demand with no count in front of it is a workspace that has fully stopped on you.
DemandWhat the workspace is asking for, in that demand's own tone. The table below lists them.
Ageoldest 10m, for 3m, just finished 3m ago, until 3:45 PM. A wait is shown in its largest unit only (2h, not 2h 15m). Split out of the sentence and drawn in the quietest ink on the row, because it is the one fragment asking for nothing.
Path hintA fragment of the path, only where this project's folder name collides with another registered project's. A plain basename is never shown, because that is already the name beside it.

Every state phrase leads with its number, so it can be scanned against the running count in front of it without reading a sentence:

StateWhat the demand reads
Directory goneDirectory not found
Agents waiting on you1 waiting / 3 waiting, plus · 1 blocked when some of them are, and the wait age (for 3m for one agent, oldest 10m for several). It says "waiting" rather than "needs input" because an agent that finished its turn settles at its prompt the same way as one that asked a question.
Agents blocked on an error2 blocked
Finished, not yet seen1 ready for review · just finished 3m ago, or 3 ready for review · 4m–2h ago
The Assistant itselfAssistant blocked, Assistant waiting or Assistant working, only where it is not just repeating what the agents already say
Agents snoozed1 snoozed · until 3:40 PM, stated once, never counting down
Finished and acknowledged2 finished · latest 20m ago, muted
Bare processes only1 process running / 3 processes running
Auto-closed to reclaim memorySuspended to free memory

The switcher counts a completion as seen after its project has stayed on screen in a focused, visible window for about two seconds. A new completion starts its own dwell, and elapsed time alone never clears unseen work. For the per-agent hand-back view and its read controls, see Pilot hand-backs.

Working is deliberately not in that list. It is the second axis, not a state that has to win a contest to be reported, so the running count survives a wait, a snooze and a completion all outranking it.

A project with nothing running and nothing to say has no status line in the switcher at all. The underlying "Opened 13h ago" fallback exists, but the switcher declines it: on twenty rows it is twenty timestamps nobody reads, and in a frecency-ordered band a bare time-ago is easily misread as the sort key.

A few small markers sit beside the name. A window icon means the project is open in another window, and choosing the row goes to that window (see One window per project). A muted bell means you have muted the project's notifications. In search results, where there are no band headers, the row you are in carries a Current label on the right.

The mark in front of the row

The mark carries only the two facts the line elaborates, and it carries them in color: green and filled when something is executing, amber when something has stopped and is waiting on you, red when something is blocked on a failure, and the completed color when finished work is ready for review. When work is running and waiting at once it is a two-tone pie, split in the proportion of the two counts (three runs against one wait draws three-quarters green), with a floor wide enough that one agent among fifty still reads as a wedge rather than a rendering artifact. A hollow ring means settled: finished and seen, or suspended to free memory. A dashed ring means snoozed. A dormant project draws no mark at all, since its presence in the list already says it is open.

One exception: a stopped workspace whose agents will come back when you open it, such as a project you put to sleep, draws a solid gray dot. A screen reader hears it as "3 agents will resume". It never displaces a colored mark, because what a workspace is doing now outranks what it would come back with.

Demand takes the mark first; liveness only claims it when nothing is asking. So a project quietly running four agents marks itself green rather than leaving the slot empty, and a hollow ring never lands on a row with something in flight.

The palette header carries the same reading for the whole fleet (3 running · 1 assistant working) and disappears when nothing is executing anywhere, so its absence is as readable as its content.

Note

Blocked agents are a subset of waiting agents, so a project with three stopped agents, one of them on an error, reads 2 waiting · 1 blocked. Collapsing it to "1 blocked" would hide two agents that are still waiting on you.

Sorting the Other projects band

The Other projects header is itself the sort control. It offers three modes:

ModeOrders by
Most used (default)Frecency, then last opened, then name.
RecentLast opened, then name.
A to ZName.

The visible trigger only appears once the band holds four or more rows: below that there is too little order for the control to be worth advertising. The preference still applies, and right-clicking the header reaches the same radio group at any size. The Welcome Screen's project list honors the same setting, so the two surfaces never disagree about order.

The setting is scoped to this band alone. Needs attention, Pinned, Running and Unavailable each encode a decision of their own: asking for A-to-Z in the residual band is not asking for your blocked agents to be alphabetized.

The Other projects header is the sort control; right-click reaches it below the four-row threshold

How frecency works

"Most used" ranks on a frecency score: one exponentially decayed number per project that folds frequency and recency together.

  • The half-life is four days. A score is decayed from the moment it was last written, every time it is read, never compared as a stored snapshot, because that would be comparing numbers frozen on different dates.
  • A counted open adds 1.0.
  • A project you have registered but never opened starts at 0.5: below one deliberate open, above the long-dead numerical tail. Registering it is itself evidence you care, and that prior decays away like any other access.
  • Increments are debounced to one per project per five minutes. Bouncing rapidly between two projects is navigation style, not engagement; counting every hop would let the pair you are toggling bury everything else. The "last opened" timestamp still updates on every switch.

There is no new-project boost beyond that 0.5 prior, and frecency does not order the switcher as a whole, only the Other band in Most used mode, plus tie-breaks in search.

Searching

Typing collapses the bands into one ranked list that mixes projects and scratch workspaces. Projects are scored on both name and path; scratch workspaces are scored on name only, since their paths are UUIDs under Daintree's own directory and a fragment of one disambiguates nothing.

Scoring rewards exact substrings, word-boundary hits and consecutive runs, and penalizes gaps, so a match has to be anchored to the words it came from and stay near them. Ranking then reads, in order: how well the name answered the query (exact, then prefix, then substring, then a scattered match, then a path-only one), what the workspace is asking of you (blocked, then waiting, then ready for review, then merely working, then nothing), how many agents are asking, the raw text score, projects ahead of scratches, and finally frecency for a project and last-opened for a scratch.

Live agent activity is a tie-break inside a name tier and can never climb out of one: two workspaces sharing a name prefix stop being ordered by frecency alone, but a worse-matching name never overtakes a better one because something started running in it. The activity reading is also frozen for the life of the palette session. Counts arrive continuously over IPC, and ranking against the live numbers would move a row out from under the pointer between deciding to click and clicking, and would re-aim a pending ↵.

One mistyped character

A workspace whose name is within a single edit of what you typed is still offered a seat. The recovery is narrow on purpose:

  • It matches on the name only, never the path.
  • The match has to start at a word boundary, so a typo of "ebsite" is not recovered from inside "Website".
  • Exactly one edit, never two, and it has to land inside a word of at least four characters. There is nothing to recover in a two-letter token, and no way to tell a typo of it from a different word.
  • The query itself has to be at least four characters.

Recovered rows are seated strictly below every clean match, and the candidates are computed on every keystroke rather than only once the clean results come back empty. Both rules exist for the same reason: a fallback that switches on emptiness reorders the rows under your pointer at the keystroke that empties the list. Appending underneath leaves the strict results' contents and positions untouched, so the only thing typo tolerance can do to a query that already worked is add rows beneath it.

Scratch workspaces in the switcher

While browsing, scratch workspaces live in their own collapsible Scratch section below the project list, with a count badge on the header and a New scratch workspace… button at its foot. Expanded while empty, it reads "Create a scratch workspace for a quick one-off task".

Scratch rows carry the same agent-activity status line project rows get (the same sentences and the same tones) minus the states a scratch has no concept of: there is no missing directory, no auto-parking, and no path hint. In search results a scratch row is tagged with a muted · Scratch after its name.

Right-clicking a scratch row offers Rename scratch, Save as project… and Delete scratch…; right-clicking the section header offers Delete all scratch workspaces, which is also a visible button. Full details are on Scratch Workspaces.

Projects on other hosts

Once you have added a remote host, the switcher lists the projects of the host this window is on, then an Other hosts section: the projects on every other connected host, and on this machine when the window is on a host, grouped under each host's name with their paths. Hosts that aren't connected are left out, and your search filters these rows too.

Choosing one moves this window to that host and opens the project there; Command-Enter Control-Enter Control-Enter or a Cmd-click (Ctrl-click on Linux) opens it in a new window instead. Moving a window doesn't move any terminals or agents: each stays on the machine it runs on. See Other Hosts in the Project Switcher.

One window per project

A project has one live view across the app, because two views would attach to the same terminals and resize one shell from two places. When another window already holds a project, whether on screen or kept warm in its cache, the row carries a window icon, the footer's Enter hint reads Go to window, and choosing the row brings that window forward and shows the project there instead of opening a second copy. The same rule applies to Open Recent, folder drops and other ways of opening a folder; see Windows.

Moving or renaming a project

Choose Move or rename project… in a project row's menu, or Locate moved project for a missing folder. The same dialog is available from Project Settings.

There are two modes:

  • Move: Daintree performs the rename itself. Same volume only; a cross-volume destination is refused rather than silently copied.
  • Reattach: the folder was already moved outside Daintree, and you point Daintree at where it is now. The dialog, titled Locate moved project, shows the old path under Last seen at and asks for the new one under Now at; Reattach project confirms.

Before you commit, the dialog previews the blast radius: the old and new paths, how many panels will have their stored paths rewritten, how many terminals will be gracefully stopped ("they restart at the new location"), and which linked worktrees will be repaired. It also breaks down what happens to each running agent's conversation, riskiest first:

TierWhat it means
Conversation can't be resumedThis agent has no way to resume the conversation after a move.
Provider migration requiredThe provider can't resume this conversation at the new path.
Resume after move unverifiedResuming this conversation after a move isn't confirmed.
Conversation stays with the folderIt resumes from the project folder, which moves with it.
Resume supportedExpected to resume automatically at the new location.

The window's renderer and its terminal instances are never torn down, so the move is not a reload. A few conditions block it outright and disable the confirm button: a relocation already running for this project, a destination that another project is registered at, something already at the destination path, a destination inside the project's own folder, a missing parent folder, a reattach target that doesn't exist, a cross-volume move, and a running Daintree Assistant: "Stop the Daintree Assistant for this project before moving it."

The row context menu

Right-click any project row:

ActionWhat it does
Open in new window / Go to windowOpens the project in its own window, or, when another window already holds it, reads Go to window and brings that window forward. Hidden for the current project, a missing one, and one this window already holds.
Pin project / Unpin projectMoves the project into (or out of) the Pinned band.
Copy pathCopies the project's directory path.
Move or rename project…Opens the relocation dialog. See Moving or renaming a project.
Stop all agentsTerminates every running session in the project, behind a confirmation. Only shown when something is running.
Sleep projectStops the project's terminals and agents the way quitting does, keeping their sessions for the reopen, and frees its memory. Offered on any open project, including the current one. See below.
Close projectOn the current project: closes it and returns the window to the Welcome Screen.
Remove projectOn any other project: drops it from the list. Files on disk are untouched.
Locate moved projectOnly on a missing project. Opens the reattach flow.
Open on… ›Once a remote host exists: a submenu of the other hosts, each marked with whether it has the project (a check, clone, or grayed out as not connected). Opens the dialog that brings the project and its branch across through Git. See Continue a Branch on Another Host.

Keyboard

Inside the palette, arrow keys walk the list and the footer hints react to the modifiers you hold: ↵ Switch becomes Command-Enter Control-Enter Control-Enter New window while the meta key is down. On a row another window holds, both keys read Go to window. A highlighted scratch row drops the new-window hint, because a scratch has no second window to open. The footer also carries All agents, which opens Pilot, and Right-click for more.

Command-Backspace Control-Backspace Control-Backspace on a highlighted project row opens the same remove confirmation the context menu does.

Four global shortcuts touch workspaces and their agents directly:

ActionShortcut
Open project switcher Option-Command-P Control-Alt-P Control-Alt-P
Switch to last workspace Option-Command-= Control-Alt-= Control-Alt-=
View all agents (Pilot) Option-Command-O Control-Alt-O Control-Alt-O
View this project's agents (Pilot, by worktree) Option-Command-I Control-Alt-I Control-Alt-I

Switch to last workspace goes to the workspace this window was in before the current one, with no palette and no overlay. It is a workspace rather than a project on purpose: a scratch workspace is a valid destination, and returning to one used to be unreachable. Running it again returns you to where you started, which gives you Alt-Tab-style toggling between two workspaces. All four bindings are remappable in Settings > Keyboard Shortcuts.

Freeing memory

A background project is not free. Its terminals keep running and its renderer stays resident, which is exactly what makes switching back instant, and exactly what costs RAM. Two mechanisms give that memory back.

Sleep project

Sleep project, on a project row's context menu, puts that one project to sleep the way quitting puts every project to sleep. It stops the project's terminals gracefully, keeping each agent's session for the reopen, and reclaims its cached renderer views and workspace host. The project stays in your list, marked closed, and reopening it brings back the layout, terminal scrollback and resumable agent sessions.

It is offered on any open project that isn't missing, including the one on screen. Sleeping the project on screen returns its owning window to the project picker. When the project has running processes or agents, or is the project on screen here, a Sleep '<project>'? confirmation lists what will be stopped first; a quiet background project sleeps at once. If Daintree can't confirm the terminals stopped, the project is left open and a Couldn't sleep project toast offers Try again.

A slept project's row draws the gray resume dot when it has agents to bring back. For the whole mechanism, see Project Memory.

Auto-close idle projects

Daintree can also do this on its own. Settings > General > Hibernation > Close idle projects automatically sweeps background projects that have been idle past a threshold and hold zero terminals, closing them the same way Sleep project does. Their switcher rows then read Suspended to free memory, and reopening restores them.

BehaviorValue
DefaultOff: it is a structural lifecycle change, so it is opt-in.
ThresholdClose after 15 minutes by default; the presets are 15m, 30m, 1h and 2h
Sweep intervalEvery 5 minutes, after a 2-minute quiet period at startup
Never touchedAny project active in any window, any project with a live terminal, and any project running the Daintree Assistant

The terminal gate is absolute: one live terminal means the project is skipped, because agent scrollback is not something to destroy silently.

When the machine itself runs short of memory, the high-memory notice in the sidebar footer offers Sleep idle projects, which sleeps background projects with no agent mid-task after you confirm them by name. See The memory notice.

Warm and cold switching

A recently used background project can keep a live Chromium renderer in the view cache. Switching to a project that still has one is a warm switch: the cached view is re-attached and repainted, without booting a new renderer, and focus returns to the terminal you left. Switching to one that doesn't is a cold switch: a renderer has to load and rebuild the project UI.

Rather than freeze on the outgoing project for that whole boot, a cold switch reveals the incoming view as soon as its themed first-paint skeleton is in the DOM before React mounts. The skeleton is an opaque themed cover over the view's own themed background, which gives the incoming project a themed loading surface while it boots. Actual latency and memory use depend on the project and machine.

If the incoming view never paints, the switch is cancelled rather than leaving you on a blank frame: you stay in the project you were in, and a Couldn't switch project toast says "The project didn't finish displaying, so the switch was cancelled" and offers Try again.

Background projects also stop doing work you can't see: git-status polling, fetches and PR checks are all paused while a project is hidden, and hidden cached views drop out of full-rate terminal work.

Cached project views

The cap on how many project views stay warm lives at Settings > Terminal > Performance > Project views > Cached project views, as a choice from 1 to 5. Changes apply immediately; eviction happens on the next switch if you dropped the cap below what is currently cached.

The cap counts the active view, so N means N − 1 warm background views. On first launch the default scales with total system memory, because every extra warm view converts a cold switch into an instant one and capable machines can afford the rotation:

Total system RAMDefault cached views
64 GiB or more5
32 GiB to under 64 GiB4
16 GiB to under 32 GiB3
Under 16 GiB2
RAM can't be read2

The hardware default only applies when no preference is stored, or when the stored value is out of range. Once you set it yourself, Daintree leaves it alone. The row's description names the default for this machine ("Default on this machine: 3"), and a reset control appears on the row once you have changed it.

Tip

The Hardware-recommended limits row and its Reset button, on the same Performance tab, recalculate the three panel limits from this machine's hardware. They do not touch Cached project views.

What gets evicted

When the cache is over its cap, Daintree evicts least-recently-used first, in this order of preference:

  • Idle views go first.
  • A view with an active agent is evicted only once no idle view is left.
  • A view that an MCP client session is bound to goes after that, because evicting it breaks the binding until you reopen the project. A view with an MCP request in flight is skipped outright until the request finishes.
  • A project with Keep workspace resident turned on in its settings is given up last. Low memory can still unload it.
  • A view with a running Daintree Assistant session is never evicted, at any pressure level. This is the view the session is pinned to, while its Claude Code or Codex process is still alive. Destroying that view would end the session and kill the CLI's process tree, including any subagent or background shell it spawned, and would buy no measurable memory, because the Assistant's process lives outside the renderer. Agents it launched into their own panels are not part of that tree.

Assistant-pinned views still count toward the cap. So that two running Assistant sessions and the active view don't fill a cap of three and evict every other project the moment you leave it, Daintree keeps room for one more ordinary warm view beside them. A cap of 1 never reserves that slot, and critical memory pressure withdraws it.

Eviction destroys the UI layer, not the work. Terminals, PTYs and agent processes live outside the view and keep running; the next visit to that project is simply a cold switch.

Available system memory can also lower the effective cap below what you configured. Above the warning threshold your setting stands; between the warning and critical thresholds the cap steps down as available memory drops, so warm switching degrades gradually; below the critical threshold the cache collapses to the active view alone. On macOS, a kernel memory-pressure warning sustained alongside heavy swap use also counts as critical, because a machine deep in swap can still report comfortable free memory. This ladder is decoupled from the resource profile: it reacts to memory, not to battery or thermal state.