tmux Backend

TermFlow can back a terminal with tmux so that its content reflows when you resize — lines that were wrapped at a narrow width re-wrap to fit a wider window instead of leaving the old line breaks baked in.

Why it exists

A normal PTY bakes line breaks into its scrollback: once a long line wraps at 80 columns, widening the window later won't un-wrap it. When a terminal is tmux-backed, a resize asks tmux to re-lay-out the content at the new dimensions and hands the reflowed text back to the display, so history stays readable at any width.

Availability is detected once, at startup:

• Linux / macOS — native tmux found in PATH (or a common location such as /usr/bin/tmux).
• Windows — tmux running inside a WSL distribution (the "WSL fallback"). TermFlow shells out through wsl.exe to a distro that has tmux installed.

If tmux is not available, TermFlow silently uses its standard portable-pty backend instead. Everything still works — resizing still changes the PTY dimensions — but content does not reflow.

Checking availability

The local API exposes a status endpoint that reports what TermFlow detected:

curl http://127.0.0.1:42031/api/system/tmux-status

On Linux or macOS with native tmux:

{
  "available": true,
  "tmux_path": "/usr/bin/tmux",
  "wsl_distro": null,
  "active_sessions": 0
}

On Windows, with tmux provided by a WSL distribution:

{
  "available": true,
  "tmux_path": "wsl.exe",
  "wsl_distro": "Ubuntu",
  "active_sessions": 2
}

When tmux is not detected:

{
  "available": false,
  "tmux_path": "",
  "wsl_distro": null,
  "active_sessions": 0
}

Field	Type	Meaning
available	boolean	Whether tmux can be used (native or via WSL).
tmux_path	string	Path to the tmux binary, or "wsl.exe" when tmux runs inside WSL; empty when unavailable.
wsl_distro	string | null	The WSL distribution hosting tmux (Windows only); null on native Linux/macOS.
active_sessions	number	Count of currently live tmux-backed sessions.

Localhost is unauthenticated by default

GET /api/system/tmux-status lives on TermFlow's local API. In the default localhost-only mode it is bound to 127.0.0.1 and needs no token. A bearer token is required only when you turn on Expose on local network. See Local API and auth.

Platform support at a glance

Platform	How tmux is provided	Reflow on resize
Linux	Native tmux in PATH	Yes, when tmux is installed
macOS	Native tmux (e.g. via Homebrew)	Yes, when tmux is installed
Windows + WSL	tmux inside a WSL distribution	Yes, when the distro has tmux
Windows without WSL	portable-pty fallback	No reflow

Installing tmux

Ubuntu / Debian (including inside a WSL distro): sudo apt update && sudo apt install tmux. macOS: brew install tmux. Restart TermFlow afterward so it re-runs detection.

For power users: the reflow-aware endpoints

Two tmux-aware REST routes back this feature. TermFlow calls them for you on resize; you rarely need them directly.

Endpoint	Purpose
POST /api/terminals/:id/resize-reflow	Resize a terminal and, on the tmux backend, return the reflowed content. The response includes reflow_applied (true only when tmux handled it).
GET /api/terminals/:id/capture	Capture a terminal's current content (optionally with scrollback).

On a non-tmux terminal, resize-reflow still succeeds but returns reflow_applied: false with no reflowed content — the caller falls back to a plain resize.

An honest note: Reflow is a display convenience, not a full multiplexer. Full-screen TUI apps (vim, htop, and similar) redraw themselves and generally won't benefit from it, and on Windows without WSL there is no reflow at all — the terminal simply behaves as a standard PTY. tmux backing is used only for content reflow; TermFlow does not surface tmux windows, panes, or key bindings.

Next steps

• Split panes — resizing panes is where reflow matters most.
• System and processes API — full reference for tmux-status and the other system endpoints.