starred/orca
1
0
Fork 0
mirror of https://github.com/stablyai/orca.git synced 2026-10-30 08:37:49 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(hibernation): describe per-pane reclaim and per-tab foreground protection (#33983)

Browse Source 
Automatic hibernation checks and stops each agent pane on its own and only
protects terminal tabs that are visible on screen, so other tabs in the
active worktree can still sleep. Update the hibernation page to match:
drop the "hibernate together as a unit" claim, scope the foreground rule
to visible tabs (active tab, other split groups, Activity page), separate
manual whole-worktree sleep from automatic per-pane reclaim, and describe
resume as happening when you return to the agent's tab.

Fixes #33940

Co-authored-by: Neil <neil@stably.ai>
This commit is contained in:
berce
2026-10-27 05:19:13 -07:00
committed by GitHub
co-authored by Neil
parent b35fb1ccfb
commit 9e8c601861
1 changed files with 6 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/site/content/docs/agents/hibernation.mdx
+6 -6
View File
@@ -1,11 +1,11 @@
---
title: Agent hibernation
description: Let Orca pause idle background agent terminals and auto-resume them when you reopen the worktree.
description: Let Orca pause idle background agent terminals and auto-resume them when you return to them.
---
import { Callout } from '@/components/docs/prose'
When you keep dozens of worktrees open, idle agents add up — each one is a live PTY holding a model session in memory. Agent hibernation lets Orca quietly stop those terminals once they've been done and untouched long enough, then resume the same session the next time you open the worktree.
When you keep dozens of worktrees open, idle agents add up — each one is a live PTY holding a model session in memory. Agent hibernation lets Orca quietly stop those terminals once they've been done and untouched long enough, then resume the same session when you return to that agent's tab.
<Callout title="Experimental">
Agent hibernation is off by default. Turn it on under **Settings → Experimental → Agent
@@ -17,7 +17,7 @@ When you keep dozens of worktrees open, idle agents add up — each one is a liv
Orca only hibernates an agent terminal when **all** of the following are true:
- The agent is in a **done** state — it has finished its last turn and isn't waiting on input.
- The terminal isn't in the active worktree or any worktree currently rendering a foreground terminal.
- Its terminal tab isn't visible on screen (the active tab, a tab shown in another split group, or a terminal shown on the Activity page). Other tabs in the active worktree can still hibernate.
- It hasn't received keystrokes since the agent finished.
- The agent is one with a [resumable session](/docs/agents/session-history): Claude, Codex, Gemini, Antigravity, OpenCode, Pi, MiMo Code, Droid, Grok, Devin, or OMP.
- It's been idle for at least the configured idle window (default 30 minutes).
@@ -25,9 +25,9 @@ Orca only hibernates an agent terminal when **all** of the following are true:
- No [orchestration](/docs/cli/orchestration) Dispatch is still unsettled (`pending`, `dispatched`, or unknown). Sleep is allowed again after runtime-confirmed `completed`, `failed`, or `circuit_broken`.
- No live subagent / teammate roster remains on the pane (provider "done" alone is not enough while children are still attached).
A terminal that fails any check stays running. If a worktree has multiple agent panes, they hibernate together as a unit so a partially-paused worktree never ships.
A terminal that fails any check stays running. Each agent pane is checked and hibernated on its own, so a finished pane can sleep while a sibling pane or tab in the same worktree keeps running.
You can also sleep worktrees manually from the sidebar (including **Sleep with Descendants** when nested children exist). See [Worktrees](/docs/model/worktrees). Manual sleep keeps **finished** and **interrupted** resumable sessions so reopening the worktree can still relaunch with the same resume flags — it does not wipe those session records just because the pane was no longer "live."
Manual sleep is different: it stops the whole worktree at once. Sleep a worktree from the sidebar (including **Sleep with Descendants** when nested children exist). See [Worktrees](/docs/model/worktrees). Manual sleep keeps **finished** and **interrupted** resumable sessions so reopening the worktree can still relaunch with the same resume flags — it does not wipe those session records just because the pane was no longer "live."
## Tuning the idle window
@@ -45,7 +45,7 @@ The sidebar filter menu controls whether sleeping worktrees are shown. If you hi
## Resuming
When you open a hibernated worktree, Orca relaunches the agent CLI with the same resume flags it would use from [Agent Session History](/docs/agents/session-history) — `claude --resume <id>`, `codex resume <id>`, and so on — so the conversation, working directory, and provider session pick up where they left off. There's nothing to click; the resume happens as part of bringing the terminal back into the foreground.
When you switch back to a hibernated agent's tab, Orca relaunches the agent CLI with the same resume flags it would use from [Agent Session History](/docs/agents/session-history) — `claude --resume <id>`, `codex resume <id>`, and so on — so the conversation, working directory, and provider session pick up where they left off. There's nothing to click; the resume happens as part of bringing the terminal back into the foreground.
Resume also reuses the launch command, arguments, and private environment captured when Orca first opened the agent.