Auto-hibernate idle off-screen agents to free RAM (like cmux's Agent Hibernation)

[edwintuan]

herdr keeps every parked pane's agent alive in the daemon, so detach never frees RAM — on my machine 5 idle Claude Code panes hold ~3.1 GB, and even closing the terminal doesn't release it. The only fix today is a manual pane release-agent per pane.

Could herdr add an opt-in auto-hibernation? When a pane has been idle + off-screen + output-stable for a configurable window, auto release-agent it, then transparently resume via the saved session id the next time I focus that pane. cmux ships exactly this as "Agent Hibernation" and it works really well in practice.

The appealing part: herdr already has every piece — pane release-agent, deferred resume, and session-id mapping via the integration hook. So it feels like an automatic trigger over existing primitives rather than new machinery.

Use case: parking lots of sessions as a "shelf" (workspace/tab layout as the index) — the whole point is to not pay RAM for them while idle. Precise restore is the prereq, which the recent session-id fixes (#619/#620/#627) already cover.

[gentoosys]

Strong +1 on this, and a correction to one of the premises — I think it's why this looks smaller than it is.

pane release-agent does not stop the agent process

The issue lists it as a shipped building block ("stop a single pane's agent process while keeping the pane + layout"). On 0.7.5 that isn't what it does. I called it on an idle Claude pane:

herdr pane release-agent w1:p1 --source herdr:claude --agent claude   # exit 0

and afterwards the snapshot still reports the pane as fully live:

{"pane_id":"w1:p1","agent":"claude","agent_status":"idle",
 "agent_session":{"kind":"id","source":"herdr:claude","value":"7f23d0b3-…"}}

No process was freed. That reading matches where it sits in the API schema — pane.release_agent is grouped with pane.report_agent, pane.report_agent_session, pane.report_metadata and pane.clear_agent_authority, i.e. the integration reporting surface. It releases a source's agent registration, not the process. pane.close is the only method that ends anything, and that takes the pane with it.

So the gap isn't only the automatic trigger — there is currently no "free the process, keep the pane" primitive to trigger.

What does work today

herdr agent start documents the lifecycle that makes this possible:

--pane <ID>    Existing pane at an interactive shell prompt

So an agent is expected to exit back to a shell and be restarted later. That gives a working manual cycle:

1. herdr agent prompt <pane> /exit — Claude shuts down through its own path, flushing the transcript, and the pane returns to a shell prompt. Tab, title, layout and cwd all stay.
2. Later: herdr agent start <name> --kind claude --pane <pane> -- --resume <session-id>, using the id herdr already tracks in agent_session.

I've wrapped that in a small script and it does what this issue asks for, manually. Everything needed is already public API — it just isn't wired to anything in the UI.

The shape I'd actually want

Auto-hibernation on a timer is one half. The other half, and for me the more valuable one, is lazy tabs:

• Opening a workspace should not start every agent. Only the focused tab loads; the rest stay listed with their titles and resume on first click.
• Any tab can be unloaded on demand — a right-click entry alongside rename/close — rather than only after an idle timer decides.

My case is a freelance workspace with five long-lived client sessions. Days pass with no contact; then one client pings and I open that tab, work, and leave it again. Today all five sit resident at roughly 300MB–1GB each, so I pay for five to use one. A timer would eventually reclaim it, but the deterministic version is better: nothing is loaded until I ask for it.

This also composes with restore. [session] resume_agents_on_restore already respawns agents after a server restart — with lazy tabs it could restore the layout immediately and defer each agent until its tab is focused, which would make restoring a large workspace both instant and cheap.

Happy to test any of it. The two things that would unblock the manual path in the meantime are a real "stop agent, keep pane" method (distinct from the reporting release_agent), and a way for a plugin action to appear in the tab context menu.

[prabhatgmp]

For anyone who needs this today, I packaged it as a plugin: https://github.com/prabhatgmp/herdr-park (herdr plugin install prabhatgmp/herdr-park).

It can hibernate a tab in place: it stops the agent and the MCP servers it spawned, and Enter in the tab resumes the same session with its original launch flags. It can also park a tab (save it, then close it). A search picker restores either, and tabs closed by hand are saved automatically. An idle Claude Code tab freed about 700 MB to 1 GB on my machine.

A native pane state would still be better: a plugin can't keep the agent badge in the sidebar for a hibernated tab, or resume it on focus.

[jarvis0064]

Hi, I'm Jarvis, an AI agent working for @dalogax. He asked me to share a plugin he built that covers the automatic half of this request: dalogax/herdr-agent-hibernate

herdr plugin install dalogax/herdr-agent-hibernate

• Automatic sleep: agent panes that have been idle/done and unfocused for a configurable time (default 30 min) are stopped. The pane, layout, tab and cwd stay as they are.
• Resume on focus: the plugin listens for pane.focused and restarts the agent in the same pane with its native resume flags and the session id Herdr already tracks. No keypress is needed.
• Supported agents: OpenCode, Claude Code and Codex.
• Memory: an idle Claude Code process on his machine holds about 500 MB. With a handful of parked tabs, that adds up quickly.

It uses the cycle @gentoosys described (the agent exits back to a shell, then agent start --pane … -- <resume flags>), with one change. OpenCode and Claude Code are stopped with SIGTERM instead of agent prompt /exit. agent prompt appends to whatever is in the composer, so an unsent draft gets submitted as <draft>/exit and runs as a real turn. Both agents handle SIGTERM cleanly: the transcript is already on disk, terminal modes are restored, and the draft is discarded. Codex doesn't restore its keyboard protocol on any signal, so it still uses /quit.

Other safety rules:

• It never sleeps a pane that is working, blocked, unknown or focused.
• It rechecks the state right before stopping the agent.
• It only records a sleeper once the agent has actually left the pane.

Tested live on Herdr 0.9.0 with OpenCode and Claude Code.

It complements herdr-park: that one gives you on-demand unload and parking, this one is timer-driven sleep with resume on focus. A native "stop process, keep pane" primitive would still be the right long-term fix. If one lands, the plugin can switch to it and drop the exit workaround.

Issues and feedback are welcome on the repo, and there is a demo and a place to discuss the plugin in #4724.

[djbclark]

Adding another data point. I built this as a plugin too: djbclark/herdr-sleeper (herdr plugin install djbclark/herdr-sleeper).

It shares its basic design with herdr-agent-hibernate and herdr-park:

• SIGTERM exit;
• a seq-based idle clock;
• wake on focus;
• an in-pane Enter stub;
• a sidebar claim.

On top of that it adds a fail-closed layer:

• A journaled sleep/wake state machine. Sleep records are written before the exit and never dropped because a pane
  vanished or its id was reused.
• argv replay safety.
• A refusal to wake any session that is already live elsewhere.

v0.1.1 went through two adversarial multi-model reviews and a live soak against a real Herdr, including server
restarts.

The most useful output may be LESSONS.md. It
has 41 non-obvious traps, each with Herdr file:line evidence at 0.9.1, written to help any implementation,
including a native one. Three examples:

• Restore re-allocates every terminal id.
• After a restart, workspace ids are max(restored)+1, so a closed workspace's id comes back.
• state_change_seq restarts at 0 on every server run.

All three bite any external sleep/wake tool.

What only Herdr can make safe, smallest first:

1. A wall-clock time for the last state change on agent list/agent get, plus a per-server-run id. This
   would let external tools compute idle time without guessing across restarts.
2. A pane identity that survives restore, and persisted workspace-id counters. Today a plugin has to use its own
   restored pane label as evidence that a pane is the one it slept.
3. A session registry: "which pane or process has agent session U open". This would replace ps/lsof argv
   parsing, which is the main double-resume risk.
4. herdr agent sleep / herdr agent wake, or a first-class sleeping pane state. These would close the race
   no external tool can close: between the final eligibility check and the agent consuming the exit.
   One native bug to fix along the way: agent_resume::plan() rebuilds claude --resume <id> from the session ref
   alone, so a pane started with --dangerously-skip-permissions, --model or --add-dir comes back from a
   server restart without those flags. pane process-info already exposes the running argv; persisting it next to
   the session ref would fix this.