Restore Session

  • Desktop, mobile and web
  • All plans
View as MarkdownFeature page

What it does

Brings back your workspace after a quit: the projects that were open, the agent terminals, the dev command terminals, and the window at its previous size and position. On quit, AgentsRoom asks whether to restore on the next launch and tells you what is open (3 agent terminals and 2 dev command terminals). On launch, the same projects reopen and each agent process is re-spawned when you navigate back to it. Dev command tabs come back idle and wait for a click on Start, unless Restore commands on launch (restoreDevCommands) is on, in which case the commands still running at quit are started again. Separately, when an agent restarts, it can resume the CLI's previous conversation instead of starting from a blank context.

Where to find it

  • Quit dialog: Quit AgentsRoom? with Restore on next launch, Quit without restoring and Don't ask me again.
  • Settings > Global settings > On quit: Ask every time, Always restore, Never restore; Start agents automatically at launch; Reopen at the previous window size; Open the window on (one radio per connected screen, the primary one marked (primary)).
  • Settings > Terminal > Restore previous session (resume the CLI conversation).
  • Restore commands on launch in the Commands modal: relaunch the dev-command terminals that were running.
  • On a reopened agent: the Restore past agent card above the composer, named Previous session when the conversation has no title, with Resume, Ignore, Don't ask for this agent, Don't ask for this project. The same card appears on the phone.

How to use it

  1. Quit with Cmd Q (Ctrl Q) or the close button. Choose Restore on next launch. Tick Don't ask me again to make the choice permanent (changeable in Settings). A quit you did not ask for (the app restarting itself to install an update, or the system shutting down) never asks: the snapshot is taken and restored at the next boot even under Never restore, for that one boot only (fixed in 1.181.0).
  2. Next launch: the projects and terminals come back. Agent processes start when you open them, or immediately if Start agents automatically at launch is on.
  3. When an agent reopens and a previous CLI session exists, the Previous session hint offers Resume: the agent continues yesterday's conversation. Ignore starts fresh this time; the two "Don't ask" options silence the hint per agent or per project.

Changing the model does not lose the conversation. A Temporary launch override from the footer, or a provider and model pair picked for one agent, keeps the saved conversation when only the model changes: Restart agent so the override applies, and the agent resumes where it was, on the new model (in a team, each role finds its step again). Only a change of provider starts a fresh conversation, because a conversation belongs to a CLI, not to a model. Fixed in 1.181.0; before that, any override restarted from zero. An override that changes only the account (same CLI) keeps the conversation too, since 2026-09-20: the transcript is brought to the launch account and resumed there (see Multiple Accounts).

If the CLI refuses what it is given at resume time, AgentsRoom recovers on its own instead of leaving a bare shell: the terminal prints "The CLI refused the saved conversation: starting a new one…" and the agent relaunches on a fresh conversation, or "The CLI refused the selected model: restarting on its default model…" and it relaunches without the model (unless the model comes from your own CLI options: that one is yours to fix). Each kind of recovery runs only once, so at worst two relaunches happen and then the setup banner stays.

When the agent never started at all (its command was not found, the CLI rejected an option, an alias or function of your shell profile shadowed the CLI, or the CLI quit right after launch), the terminal is just a shell. A message sent there is refused rather than executed by the shell, and the composer names the culprit, for example: Not sent: the "codex" command was not found when this agent launched, so its terminal is just a shell. Install it or fix your PATH, relaunch the agent, then send again. Your message is kept. The same line names the refused option, the shadowing alias or the early exit when that was the cause, and your draft stays in the box either way. When the missing-command verdict came from a filesystem lookup, an I already have it link ("codex is already installed: stop showing this") lets you overrule it and relaunch. When the terminal was running and is gone ("Not sent: this agent's terminal is no longer running..."), a Relaunch agent link sits right under the message: it restarts the CLI and resumes the conversation, no need to look for the restart entry of the pane menu.

A Session name typed in the agent profile (click the agent's name in the terminal header) is kept until you clear it: it survives a restart, a resume and an app relaunch instead of falling back to the title the agent chose ("Kept until you clear it, even after a restart.").

Settings

  • restoreOnExit (global, Settings > Global settings > On quit): ask (default), always, never.
  • autoLaunchAgentsAtStartup (global, Settings > Global settings): let restored agents, interrupted team runs and missed scheduled tasks start on their own at launch; off means nothing starts until you ask.
  • restoreDevCommands (global, Restore commands on launch in the Commands modal; project override available): re-launch the dev-command terminals that were running.
  • restoreWindowBounds (global, Settings > Global settings): reopen at the previous size, position and maximized state, on the screen that was holding the window; on by default. Unchecked, the window always opens maximized.
  • windowDisplayId and windowDisplayLabel (global, Settings > Global settings > Open the window on): pin the main window to one screen, applied at the next launch; the default radio reads At its last known position (default) when the previous setting is on and Wherever the system puts it (default) when it is off. The pin decides which screen, the remembered geometry decides the size, so the two combine.
  • neverRestoreSessions (global, Settings > Terminal): kill-switch, never offer to resume a previous CLI session.
  • cliPresenceOverrides (global): the "I already have it" answers, one per CLI, set by the link in the composer hint or the setup banner.
  • neverRestoreSession (project override, Project settings): never offer resume for this project's agents.
  • restoreMode (per agent, Edit agent): ask (default, show the card), always (resume silently, no card), never (always start fresh). A global or project "never" wins over it.

Agent tools (MCP)

  • agents_resume: resume a saved agent session with its conversation.
  • agents_restart: the opposite move, for the calling agent only: its console restarts on a NEW conversation whose first message is the prompt it wrote (context checkpoint routines), with no resume offered. See AgentsRoom MCP.
  • agents_save / agents_close: keep an agent's context so it can be resumed later.

Providers

Restoring the layout works for every provider. Resuming the conversation depends on the CLI: Claude, Codex, Grok, Antigravity, Cursor, Kimi Code and oh-my-pi can reopen their own conversation, and they are the only seven. Every other provider restarts with the same role and prompt but without the CLI's own history, and no card is offered at all.

oh-my-pi (since 2026-09-25): AgentsRoom chooses the session file when it starts the agent, in oh-my-pi's own sessions folder, so the conversation is resumable from the first second, even with several oh-my-pi agents in the same folder, and it still shows in omp stats and in omp --resume from your own terminal. No card is offered for a session that never got a message, nor for one started in another folder (an agent moved to or from a worktree), because oh-my-pi would move the agent back into that folder. A /new typed inside oh-my-pi opens a file AgentsRoom does not follow: a restart then reopens the conversation from before /new (/clear keeps the same session and is fine). A session flag in the agent's CLI options (--continue, --resume, --session, --no-session…) takes over: AgentsRoom then neither names nor resumes anything.

Cursor: the CLI prints no conversation id, so AgentsRoom reads it from Cursor's own chat folder while the console runs. A Cursor agent that was never run under this version has no saved id and starts blank once.

Codex: the decorative animations of the Codex composer are disabled in the environment AgentsRoom prepares for it, otherwise an idle agent passes for a busy one and a restored Codex shows "Working…" without end (fixed in 1.176.0). A Codex run that spawned sub-agents writes one session file per sub-agent; AgentsRoom skips those and keeps the id of the real conversation, so the resume no longer fails on a session not found.

Model on resume: Claude Code, Codex, Antigravity, Cursor and oh-my-pi accept a different model than the one the conversation started on, so a forced model applies to a resumed conversation. Grok refuses a model switch on a resumed session: it resumes on its previous model.

Mobile

The layout snapshot and its restore are desktop-only: the phone simply sees the agents reappear once the desktop has restored them. The Previous session card does reach the phone, though: relaunch an agent from the mobile app and the same Restore past agent card appears above the composer with Resume and Ignore, so a run started from the sofa no longer leaves a blank CLI behind while the desktop waits for an answer. The two "Don't ask again" choices stay on the computer, because they write a setting; on the phone Ignore means this time only.

Limits

  • The snapshot is written on a real quit; closing the window is not quitting.
  • Restored agents re-spawn when you navigate to them unless automatic launch is on, so a restored project with many agents does not start them all at once.
  • Dev command terminals are relaunched with the same logic as the Start All button; a server that needs a manual step still needs it.
  • A saved window position on a screen that is no longer connected is ignored, and a pinned screen that is no longer connected falls back to the system placement (Settings then shows The pinned screen is not connected).
  • The saved geometry is machine-local: a monitor layout does not travel with the account.
  • On the phone the card is offered when the agent was started from the agent list; a session started from the console screen's own start button does not offer it yet.
  • Everything is stored locally, in the project's AgentsRoom folder and the app data; nothing is sent to a server.
  • Team mode: after a restart, coming back to a step reopens the role's current console, the one you were working with, not the console from before the restart (fixed 2026-09-19).

Common questions

  • The quit dialog no longer appears. You ticked Don't ask me again; change On quit in Settings > Global settings.
  • My agent restarted with a blank memory. Resume was declined or disabled: check Settings > Terminal > Restore previous session, and the project's own setting. It can also mean the CLI refused the saved conversation: the terminal then prints "The CLI refused the saved conversation: starting a new one…" and the agent relaunches fresh by itself.
  • The agent reopens but never answers, and I used to delete and recreate it. Update AgentsRoom: a CLI that rejected the saved conversation or the model used to leave a bare shell that ran your messages as commands. The agent now relaunches on its own, and a message sent to a shell is refused with "Not sent:" and kept in the composer. A CLI that quits right after launch, or a shell alias that shadows it, gets the same refusal instead of a shell running your text.
  • My Cursor agent restarted from scratch, even on the Grok model. Fixed: Cursor now resumes its conversation on restart and reopen like the other four CLIs.
  • The session name I typed keeps reverting to the agent's own title. Fixed: the name you type in the profile is now kept across restarts and resumes until you clear it.
  • After an update, my restored Codex agent shows "Working…" for hours. Fixed in 1.176.0: the Codex composer animations made an idle prompt look busy. Update AgentsRoom and relaunch the agent.
  • I restarted to install an update and my agents and terminals were gone. Fixed in 1.181.0: a restart for an update, or a system shutdown, now restores the session at the next boot even when On quit is set to Never restore. Only a quit you chose yourself follows that setting.
  • I forced another model and restarted the agent: did I lose the conversation? Not anymore (1.181.0): the conversation is kept when only the model changes, and a resumed Claude Code agent runs on the forced model. Switching the provider does start fresh, and Grok keeps its previous model on a resumed session.
  • My Codex agent fails to resume with "No saved session found" after a run with sub-agents. Update AgentsRoom: the sub-agent session files written during such a run were mistaken for the conversation. The real session is now the one resumed.
  • The same agent is shown in two places and I clicked Resume twice: "This conversation is open in another app". Fixed on 2026-09-23: the Previous session card is shared by every pane that shows the agent (the room, the ticket preview, a separate project window). Accepting it in one clears it everywhere, and a pane that finds the agent already resumed attaches to that console instead of starting a second one.
  • A resumed Claude agent replays its conversation but stays on "starting", and messages sent to it never arrive. Fixed on 2026-09-24, mostly seen on Windows: AgentsRoom now recognises the CLI's own idle prompt as the sign it is ready, and waits for the end of a long replay (several minutes for a very long thread) before delivering the resume prompt and queued mail.
  • After an update, my resumed Claude agents no longer update their tab title and notifications, and a banner says the agent stopped updating its session file. Fixed on 2026-09-28 for macOS and Linux: a resumed Claude Code conversation was relaunched without the AgentsRoom instructions, so the agent stopped reporting its status. It now keeps them. Update AgentsRoom, then restart the agent once (or resume it again) so its console picks them up.
  • Does it survive a crash or a reboot? Yes, the snapshot is on disk; the next launch offers it.
  • Can agents start by themselves at launch? Only if Start agents automatically at launch is on; it is off by default.
  • I dragged the window to my second monitor, maximized it with the green button, and it reopens on the first screen. Update AgentsRoom: builds up to 1.173.0 could remember the screen the app started on instead of the one you moved it to, when the window had been maximized from the macOS green button. The saved position is now anchored on the screen actually holding the window. To force one screen whatever happens, use Open the window on.

Related