Skip to main content

Updates

Since 0.3.0, most updates keep your terminals running. TermFlow installs the new version, restarts its window, and puts your running shells and the programs in them (Claude Code, Codex, a build, an SSH session) back where they were. Some releases can't do that safely. Those ask for a full restart, which closes every terminal, and TermFlow always asks you first.

Open Settings → Updates to see your version and whether an update is waiting. TermFlow checks for updates each time you open this page.

What the Updates Page Shows​

You seeWhat it means
You're on the latest version.Nothing to install. Check again asks the update server again.
Version X is available. Updating keeps your terminals running — they reattach to the new version automatically.An Offload update. Your terminals survive it.
Version X is available. This update closes all terminals when it is applied; you are asked to confirm first.A full-restart update. One or two reason lines below it say why.

The button for both kinds of update is Update to X & Restart. Re-check runs the check again. If something blocks the update right now, a line starting with ⚠ explains what.

Builds without the in-app updater

Some builds, such as store builds, don't include the in-app updater. They don't show the update block on this page.

Offload Updates​

An Offload update hands your running shells to TermFlow's terminal service, a small background process that owns the shells, and then restarts the app. When the new version starts, it reconnects to the terminal service and your tabs come back with their programs still running.

The terminal service can't always be replaced while it's holding shells, so for a while there can be two of them:

  • New tabs you open after the update run on the new version of the terminal service.
  • Tabs that were already running stay on the previous version until you close them. Those tabs show a small gold ⟲ icon in the tab strip. Hover it to see "Running on a previous version of the terminal service."
  • Once the last tab on the old version is closed, the old terminal service shuts itself down a few seconds later. You don't need to do anything.

A tab with the ⟲ icon works normally. If you want everything on the new version, finish what's running in it, close it, and open a new tab.

Full-Restart Updates​

A release can declare that updating to it needs a full restart. This happens when the release changes something the old terminal service can't carry across. TermFlow also asks for a full restart when the terminal service that's running can't survive the update itself.

The reason lines on the Updates page say which applies:

  • "This release requires a full restart."
  • "A running terminal service cannot survive this update."

When you click Update to X & Restart, TermFlow asks "Update to X and close all terminals?" and tells you how many terminals will close. Close terminals & update goes ahead and Cancel leaves everything as it is. Nothing is closed before you confirm. If anything changes before the update starts, such as the number of terminals, TermFlow asks again with the new details.

After a full restart your tabs and layout come back. The programs that were running in them don't.

Admin tabs

Admin (elevated) tabs are never carried across an update, Offload or full. Their shells close, and the tab doesn't come back elevated.

Agents Connected Over MCP​

During an Offload, the MCP port stays reserved, so agents don't get "connection refused" while TermFlow restarts. Calls they make in that window get a reply telling them TermFlow is restarting, that their terminals are still running, and to wait about 30 seconds and retry without recreating terminals. When TermFlow is back, the calls work again on the same address.

This needs a terminal service that supports it. Clients that use the REST and WebSocket API directly lose their connection while TermFlow restarts and have to reconnect.

Offload & Close (Without an Update)​

The same page has Offload & rebuild (keep terminals running). Offload & Close… hands your shells to the terminal service and closes TermFlow without installing anything. This is useful if you build TermFlow yourself and want to swap in a new build. Launch TermFlow again to get your terminals back.

The text above the button tells you how long the terminal service will keep your shells. If TermFlow isn't reopened in that time, the shells are closed. If the action can't keep every terminal alive right now, the button is disabled and the page says why, so nothing is lost by trying.

An honest note: Updating from 0.2.3 or earlier doesn't follow the full-restart rules on this page. Those versions keep their terminals running through every update. After you move to 0.3.0, tabs from before the update show the ⟲ icon until you close them. From 0.3.0 on, each release decides whether its update keeps terminals or needs a full restart.

Next Steps​