ResumerAgent
Menu

Docs

Safety

How ResumerAgent refuses unsafe actions, re-checks every request on the server, and keeps your session data on your machine.

ResumerAgent’s source code isn’t public yet. These pages describe how it works once it is.

Fail-closed by design

ResumerAgent can resume, attach to, pause, close and purge sessions. When it can’t confirm a session’s state, it refuses the action instead of guessing.

  • Unknown liveness blocks everything. If ResumerAgent can’t tell whether a session is live (liveUnknown), it refuses every action on it. The browser disables the buttons, and the server refuses the request on its own (canSafelyAct() in server.mjs). Each layer enforces the rule independently, so a bug in one doesn’t weaken the other.
  • The server never trusts the click. Every resume, purge, pause and close request carries only a session ID. The server looks the session up again and re-derives its state before doing anything.
  • Superseded sessions can’t be resumed. When you give a new session the same name as an old one, the old one is marked “moved to a newer session”. Resuming it would grow a transcript you’re trying to retire, so ResumerAgent refuses.
  • Pause only touches background jobs. Pause requires a live, confirmed background session (started with claude --bg) with a real ID. It runs Claude Code’s own claude stop <id>, so claude attach <id> and claude --resume both work again afterwards.
  • Close checks the process right before acting. Close requires a live, confirmed interactive session with a real process ID. Just before ending it, ResumerAgent confirms that the process ID still belongs to a claude process. That guards against process ID reuse, since ending the wrong process has no undo.
  • Destructive actions take two clicks. Purge, Pause and Close each ask for confirmation.

Purge still does what you tell it. Fail-closed stops ResumerAgent from acting on sessions it can’t verify. It can’t stop you purging a session you didn’t mean to.

What it can’t do

The expiry badge warns you when a session is within 5 days of Claude Code’s cleanupPeriodDays cutoff (30 days by default). It is a warning only. Claude Code runs its own cleanup at claude startup, outside ResumerAgent’s process, and ResumerAgent can’t stop or delay it.

Your data stays local

  • The dashboard server binds to 127.0.0.1 only.
  • It has zero runtime dependencies: only Node’s built-in node:http, node:fs and node:child_process.
  • Everything it reads comes from your own SESSIONS_ROOT, and it sends nothing anywhere.

Testing changes safely

If you work on ResumerAgent itself, never test resume, purge, pause or close against real sessions you care about. Use synthetic .jsonl fixtures, a disposable claude --bg job, or a disposable interactive session you don’t mind ending.