Skip to content
installcurl -fsSL https://get.farhelm.io/install.sh | sh

New terminals

Farhelm has changed how it runs your sessions’ terminals. Until 0.34.0, every session’s terminal, and every shell tab beside it, ran inside a Farhelm managed tmux on its host, and xterm.js drew it in the UI.

Since 0.34.0, every new terminal (a new agent session, a new shell tab) runs without tmux, and no xterm.js is involved either. Instead, each terminal is owned by a small Farhelm process that does the bare minimum to keep the terminal running, including for short periods while other Farhelm processes restart, such as during updates.

Farhelm has since stopped supporting old terminals, the ones that still ran in tmux. Earlier releases warned about them with a note at the top of each such session and a notification in the session list.

The first time a host’s Farhelm starts on a release without old terminals, it ends the tmux that ran them, and everything that still ran in them:

  • A session whose agent was still running in an old terminal now shows as interrupted, with a notification saying so. Restart starts the agent again in a new terminal and resumes its conversation; if Restart is unavailable for the session, Replace starts it anew. The new terminal starts empty: the old terminal’s scrollback and its last screen are gone.
  • A session whose agent had already stopped or exited keeps its status and gets no notification, but its terminal no longer shows the agent’s last screen, which lived in the old terminal. Restart starts it in a new terminal as usual.
  • Old shell tabs are closed. Open new ones where you need them.

Programs that old agents and tabs had left running in the background are stopped too, wherever Farhelm can tell which session they belong to. Any it cannot tell are stopped when you delete their session.

If Farhelm could not end the old tmux, it logged why and started anyway, treating those sessions as ended. An agent could then still be running in an old terminal, so Restart would start a second one beside it.

The old notification asking you to restart such a session is now greyed and marked Resolved (Read the session list says how notifications work).

tmux was intended to be as much of an implementation detail as possible, but it leaked through:

  • Farhelm exercised tmux in ways normal users don’t. We already triggered tmux crash bugs in early development which lead to setting a minimum tmux version of farhelm, and supporting an embedded musl build of tmux. This meant supporting both the embedded musl build and the native build. We already had one case of a newer tmux breaking behavior in certain environments.
  • Every session on a host shared one tmux. Upgrading tmux, or a tmux crash, ended all of them at once, much like a reboot. The new tmux replacement is meant to almost never need to be upgraded - but if and when it does, you’ll be able to do so on a per-terminal basis rather than globally for an entire host.
  • The old system involved terminal emulations occurring in two places (xterm.js and tmux). The new system has terminal emulation happening in precisely one place - the client/UI has a much more basic character grid protocol native to farhelm.

A new terminal stands on its own: a problem with one does not take the others down, and it no longer depends on which tmux version a host has.

Typing with an input method, as for Chinese, Japanese or Korean, does not work fully in Farhelm’s terminals yet. What you commit reaches the agent, but the text you are composing, and the input method’s list of candidates, do not appear at the terminal’s cursor while you type.

Emoji presentation selectors, as in ❤️, give eligible characters two columns, and text presentation selectors can make a wide character narrow. This follows Ghostty’s defaults; tmux also widened characters that are not eligible and did not narrow them.

Farhelm’s terminals drop some invisible formatting characters from program output, including zero-width spaces, text-direction marks, line and paragraph separators, word joiners, byte order marks and Hangul fillers. Those characters are also absent from scrollback, saved terminal contents and text you copy. What you type, your programs and their files are unchanged.

Two edge cases still differ from Ghostty: with wrapping disabled, a printed space in the final column is treated as empty when choosing which character a selector affects; and a terminal only one column wide drops a wide character before wrapping. The Ghostty reference for the first case and the second case show the behavior Farhelm will revisit.

Programs in Farhelm’s terminals see TERM_PROGRAM=farhelm, with Farhelm’s version in TERM_PROGRAM_VERSION. TMUX is unset. An agent started, or a tab opened, before 0.36.0 keeps the environment it started with, which still claims to be tmux, until you restart the agent or close the tab. If a startup file of your login shell starts tmux whenever it is not already inside tmux, it does so in Farhelm’s terminals too, including while the agent starts. One that replaces the shell with tmux (exec tmux) keeps the agent from starting at all, and the session’s terminal shows your tmux instead. To leave Farhelm’s terminals alone, have the startup file skip tmux when TERM_PROGRAM is farhelm.

Nothing in Farhelm needs tmux any more: not the desktop app, and not a remote host. Farhelm itself no longer runs tmux for any session either: it ends the tmux it ran old terminals in when it updates, and never starts one again.

Earlier versions installed their own copy of tmux on remote Linux hosts whose tmux was too old or missing, which was most of them (Ubuntu 24.04 and Debian 13 included). Typing tmux in a session or terminal tab on such a host ran that copy rather than the host’s own. Updating the host, or adding it again, now removes Farhelm’s copy, so tmux there runs the host’s own tmux, or is not found if the host has none. A copy that a Farhelm update before 0.18.0 put next to farhelm in a shared directory such as ~/.local/bin is left alone, since it may be yours; delete it if it is not. If you use tmux on that host, install it yourself. A tmux you had already started from Farhelm’s copy keeps running until you end it.

On a remote Linux host, once an update rewrites Farhelm’s service there, sessions no longer get the directory of the tmux Farhelm used to run added to their PATH. A tmux you installed in a directory your login shell does not put on its PATH (Linuxbrew’s, say) is found from a session only once your shell’s startup files add that directory.