Restore Session

  • Desktop, mobile and web
  • All plans

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; Reopen the last project at launch; Start agents automatically at launch; Resume agents after an update; 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): Ask each time (Restore past agent card) (default), Always resume, no card, Never: always start fresh.
  • 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 card stays until you pick one of them (it never fades out by itself), or until another agent brings this one back (since 2026-10-20): agents_resume accepts the card for you, and so does a message sent to it when A message may start the recipient is on; with that setting off, the message waits for your choice on the card. The same card appears on the phone.
  • At the top of a project's agent list, when the restore at launch left some of its tabs closed: "N sessions from last time were not reopened" with Restore (and a close button to hide it until the next launch).
  • Right-click on a project tile in the sidebar, or the ⋮ menu of a project card: Restore previous sessions (N), shown only when some of the project's consoles from last time are not running on their conversation.
  • After AgentsRoom stopped while agents were at work (since 2026-11-06): a card in the corner of the window, AgentsRoom stopped around a time, with the reason, the agents cut off and Show the log. On each of those agents, an Interrupted badge on its row and an Interrupted while working card above its composer (one line of the Restore past agent card when that one is up). The same badge and card appear 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: then every restored agent of every reopened project starts, without opening each project (fixed 2026-10-13; before, only the agents of the project on screen started, and only once you clicked into it).
  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.

Restore by hand (since 2026-10-09): when the automatic restore was skipped or failed for a project (agents not started at launch because Start agents automatically at launch is off, a project shown in its own window, agents not loaded in time, a remote server that was not reachable), Restore on the notice or Restore previous sessions in the project's menu brings back the project's tabs from last time, each agent on its previous conversation: closed ones are started, ended ones restarted, and a Previous session card waiting on a fresh console is accepted. An agent already running is left alone, and an agent you closed yourself since the launch is not counted.

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), or directly with the pencil next to that name (Rename session: Enter to save, Escape to cancel, empty to go back to the automatic title; on the phone, the same pencil next to the title in the agent console), 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.
  • warnQuitWhileAgentsWork (global, Settings > Global settings > Warn before quitting while agents are working, off by default, since 2026-11-12): a quit (the main window's close button, Cmd+Q, the Quit menu) while at least one agent is working or has work running in the background first shows Agents are still working, which lists those agents with their project and Working or Background work. Keep AgentsRoom open is the default button (Enter and Escape keep the app open), Quit anyway goes on with the quit. With every agent idle, nothing is asked. When On quit is Ask every time, the list appears inside the Quit AgentsRoom? dialog instead and Cancel becomes its default button: one dialog, never two. Update restarts, Close and update and a computer shutting down never ask. Machine setting, not synced with the account, like On quit.
  • reopenLastProjectAtLaunch (global, Settings > Global settings > Reopen the last project at launch, on by default, since 2026-11-11): bring back in front the project that was on screen at quit. Off, the launch still restores everything else (the open project tabs, the agent terminals and their conversations, dev commands, detached windows) and opens on the home screen; agents of the project that was in front start in the background as usual. It applies to every launch, update restarts included. Machine setting, not synced with the account, like On quit.
  • 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.
  • resumeAgentsAfterUpdate (global, Settings > Global settings > Resume agents after an update, on by default since 2026-10-26, off before): when AgentsRoom restarts itself to install an update (Restart to update or Reboot to install on the computer, or the update installed from the phone), every agent restored with the workspace resumes its conversation by itself instead of showing the Restore past agent card. Only that restart: a normal quit, even one that installs a downloaded update on its way out, and a plain restart asked from the phone still show the card. A "never" restore setting (global, project or agent) still wins. Machine setting, not synced with the account, like On quit.
  • 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 and alwaysRestoreSessions (global, Settings > Terminal > Restore previous session, shown as one select, since 2026-11-12): what a reopened agent does with its previous conversation, after any restart (a normal quit too) or a reopen. Ask each time (default, both off) shows the Restore past agent card; Always resume, no card (alwaysRestoreSessions on) resumes every agent on its conversation by itself, no click needed; Never: always start fresh (neverRestoreSessions on) is the kill-switch, never offered. Always applies to agents that have no restore mode of their own; Never wins over every other level. Machine setting, like On quit. The agents start as before, through the same launch queue as after an update: Always does not start more consoles, it only puts each one back on its conversation.
  • 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.
  • alwaysRestoreSession (project override, through the agents' settings tools): true = Always resume for this project's agents, false = Ask (the card) even when the global setting says Always, absent = follow the global setting. A project or global "never" still wins.
  • restoreMode (per agent, Edit agent > Session restore): Follow the default (project, then Settings) (the default: no value stored), ask (always show the card, even when a default says Always), always (resume silently, no card), never (always start fresh). A global or project "never" wins over it. After a crash, ask agents restored with the workspace resume silently too, as if set to always.

Agent tools (MCP)

  • agents_resume: resume a saved agent session with its conversation. On an agent whose console came back blank behind its Restore past agent card (after an app restart), it accepts that card, like a click on Resume (since 2026-10-20). With allowFresh: true, an agent that has no conversation to resume is opened on a new one instead of refused (since 2026-11-03); without it, a refusal never opens a blank console.
  • agents_list_live marks such an agent resumeOffered: true: it is running but does not remember its work yet. A message sent to it with agents_send resumes its conversation first, then is delivered, when A message may start the recipient is on; with it off, the message waits until you click Resume or Ignore (the personal assistant excepted: its conversation restarts every day, it gets its mail at once).
  • agents_list_live marks an agent caught in the middle of its work by the last stop of AgentsRoom interrupted (at, cause), and interruptedNote gives the reason and where the log is: its console reads as idle, but it did not finish.
  • 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

An agent cut off by the last stop of AgentsRoom carries the same Interrupted badge on its row and the same card above its composer, and closing the card there closes it on the computer too. The reason card with Show the log stays on the computer, where the log is.

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 saved continuously while AgentsRoom runs (a few seconds after each change, at most 15 s), so a crash, a power cut or a system restart keeps it; quitting only writes the last change. 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.
  • Restore previous sessions brings back the tabs of THIS launch's snapshot: it is not offered under Never restore, and it forgets everything once AgentsRoom quits.
  • 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

  • After every restart I have to click Resume on each of my agents. Can they all come back on their conversation by themselves? Yes since 2026-11-12: Settings > Terminal > Restore previous session > Always resume, no card. After any restart, a normal quit included, every restored agent resumes its previous conversation without the Restore past agent card. An agent set to Ask each time or Always start fresh in Edit agent keeps its own choice.

  • All my agents stopped at the same second. Why, and which ones were working? AgentsRoom tells you at its next launch, on a card that stays until you close it: the time it stopped, the reason, and the agents that were working and did not finish. Each of them keeps an Interrupted badge until you close its card or send it a message, because a resumed agent sits at rest and nothing tells it that it was cut off. When the computer itself stopped or restarted (a power cut, a forced restart, a system crash), the card says so: no app can write anything at that moment. Show the log opens logs/main-errors.log, where the time is written in your local time as well as UTC. The line about a stop nobody announced is written at the next launch, so look for the launch time and read last alive in it. Quitting with agents at rest shows nothing. Nothing leaves the computer except counters when usage data sharing is on. Agents read the same facts in agents_list_live (interrupted, interruptedNote).

  • AgentsRoom stops responding as soon as it reopens a project. Can it start without that project and still keep my sessions? Yes: turn off Reopen the last project at launch in Settings > Global settings (an agent can do it with settings_set reopenLastProjectAtLaunch false). The next launch opens on the home screen, with every project tab, agent terminal and conversation restored, and you open the project you want from the sidebar. Change it once while the app responds: from then on no launch brings that project in front by itself, and the restore file never needs to be edited by hand.

  • I closed the main window by mistake and every working agent stopped. Can AgentsRoom ask first? Yes: tick Warn before quitting while agents are working in Settings > Global settings (an agent can do it with settings_set warnQuitWhileAgentsWork true). From then on a quit while an agent is working or has background work lists those agents and waits; pressing Enter keeps AgentsRoom open. With every agent idle, the app quits without asking.

  • 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.

  • Start agents automatically at launch is on, yet my agents only start when I open their project, and only one or two of them. Fixed on 2026-10-13: at launch, every restored agent of every project now starts on its own. Update AgentsRoom if you still see it.

  • 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 stayed on a bare shell after a restart, under "No saved session found with ID". Fixed on 2026-10-09: when the saved conversation no longer exists on disk, AgentsRoom starts the agent on a new conversation instead of trying to resume it. If the CLI still refuses the resume, the console you are watching relaunches fresh once and says so; a resume started by an agent over MCP keeps the error visible instead.

  • 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 and kept up to date while you work; the next launch reopens it.

  • My computer shut down and after the restart everything was gone, with Start agents automatically at launch turned off. Fixed on 2026-11-02. With that setting off, the session that followed a restore was no longer saved as you worked (and with On quit set to Ask, the previous save was already used up), so a crash or a power cut reopened nothing. The workspace is now saved continuously in every configuration: the projects you had open come back, and the agents you had not restarted yet stay ready behind Restore previous sessions.

  • After a restart, the agents I had set aside in Done came back among my open agents. Fixed on 2026-11-02: an agent you marked as done stays in Done after a restart, a crash or an update, until it starts working again or you close it.

  • After a crash, my agents came back blank with a Resume card each. Since 2026-10-12, when AgentsRoom comes back from a crash (the app closed unexpectedly, or you clicked Reload on the crash screen), every agent restored with the workspace resumes its conversation by itself, no card to click. After a normal quit nothing changes: the card is still offered. A "never" restore setting (global, project or agent) still wins.

  • After a restart, my agent's conversation view only shows a colleague's message and its reply, the rest of the history is gone. Since 2026-10-20 this no longer happens. The history is not lost: after a restart the agent came back on a new, blank conversation behind its Restore past agent card, and the message was handled by that blank conversation, which is all the view could show. Click Resume on the card, above the agent's composer, to get the previous conversation back. Now a message waits for your choice on the card, or resumes the conversation by itself when A message may start the recipient is on. To skip the card after an update, turn on Resume agents after an update.

  • After a restart, my assistant (or another agent) relaunched my agents, but they had forgotten what they were doing. Fixed on 2026-10-20. After a restart each restored agent runs on a blank conversation, its previous one waiting on the Restore past agent card, and agents could not see that card: asked to resume one, the assistant was told the agent was already running and wrote to the blank console. Now agents_resume accepts its card first, exactly like a click on Resume, so the agent answers with its history. A message sent to it does the same when A message may start the recipient is on; with it off (the default), the message waits until you click Resume or Ignore on the card, and never reaches the blank console. An agent you already talked to, or whose card you dismissed, is left as it is.

  • The restore did not bring my sessions back. Can I trigger it again? Yes since 2026-10-09: Restore on the "sessions from last time were not reopened" notice of the project, or Restore previous sessions in the project's right-click menu (sidebar) or ⋮ menu (projects home). It reopens the project's tabs from the last launch, each on its previous conversation.

  • My project opened in its own window comes back empty after a restart. Its window reopens but its agents do not start by themselves. Since 2026-10-09 the window shows "N sessions from last time were not reopened": click Restore and they come back in that window, on their conversations. The window opens on the current virtual desktop: move it back (or make it full screen again on macOS).

  • Can agents start by themselves at launch? Only if Start agents automatically at launch is on; it is on by default.

  • After I click Restart to update, every agent comes back stopped and I have to resume them one by one. Check Settings > Global settings > Resume agents after an update: when it is on, after that restart each restored agent picks up its conversation by itself, no card to click. It is on by default since 2026-10-26, existing installs included (it shipped off on 2026-10-19); turn it off to get the card back. Agents set to never resume (in Settings > Terminal, the project or the agent) still start fresh.

  • 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.

  • Dev Terminals: the dev commands being relaunched.
  • Project Memory: long-term knowledge that survives across sessions independently of resume.
  • Agent Fork: duplicating a live session instead of resuming it.