Skip to main content

​
Start here

One table: whether the server is reachable, whether its wire dialect matches your binary, the three environment variables, pid/uptime/panes, and how many machine links exist. Most of what follows is a specific answer this gives you.

​
tty7: command not found

The CLI is put on PATH the first time the app launches. If it is missing:
  • Check Settings → Agents → Install the tty7 command on PATH is on.
  • On Unix it symlinks into whichever of /opt/homebrew/bin, /usr/local/bin, ~/.local/bin, ~/bin, ~/.cargo/bin your PATH already covers — if none of those are on your PATH, add one.
  • On Windows the install directory is appended to your user PATH, which needs a new shell to take effect.
  • A tty7 you installed yourself is never replaced, so an old one earlier in PATH will win.
Inside a tty7 pane it works regardless, since panes inherit the app’s environment.

​
The server is unreachable

tty7 doctor says so, and the GUI cannot open panes. Start it with tty7 server start. If you are an agent or a script, do not — tell the user instead. Starting a server they did not ask for changes what their GUI attaches to. For logs:

​
Panes came back empty

A crash, a kill -9, or a reboot takes the shells with it — that part is unavoidable. The screens should come back: tty7 keeps a capped tail of each pane’s output (256 KiB) and hands it to the pane that reopens on that id. It is consumed once. If a pane was restored, then closed, then reopened, the second time there is nothing left to restore — that is by design, not a bug.

​
”The background server is still running <build>”

tty7 updated in place, so the app is new and your panes are still served by the previous build. Restarting the server picks up the new one and ends every process in every pane. There is no hurry — do it when your panes are idle. Updates →

​
A remote machine will not connect

tty7 -m <machine> never dials a fresh connection by design — it uses a link the local server already holds. Connect from the GUI first.

​
⇥ or ⌃ R is not doing what I expect

Both are switches, and turning one off hands the key straight back to your shell:
  • Settings → Input → Prompt → Tab completion
  • Settings → Input → Prompt → History search
If they do nothing at all in a particular pane, the shell there probably has no shell integration — nushell, elvish, xonsh and friends run fine but do not get the prompt layer.

​
⌥ B types ∫ instead of moving a word

That is macOS’s default. Turn on Settings → Input → Keyboard → Option (⌥) acts as Meta.

​
CJK characters have a gap on the right

Your CJK fallback advances 1.0em while the primary face advances 0.60205em, so the glyph does not fill its two-column slot. Install Maple Mono NF CN — it is already first in the fallback chain and fits Hack exactly — or change the primary face. The full explanation →

​
A theme in my themes folder is not showing up

Settings lists it under Not loaded from the themes folder, with the reason. Usually a missing required key: background, foreground, accent, and ansi (with eight normal and eight bright entries) are all mandatory.

​
My config.json edits did nothing

If the file cannot be parsed, tty7 starts on defaults and keeps your original at config.json.corrupt — check for that file. Otherwise:
  • An out-of-range number is clamped, not applied literally.
  • An unrecognised enum value falls back to the default with a log line.
  • scrollback_limit applies to new panes only.
  • An unknown action name in keybindings is skipped with a warning.

​
Selecting text inside vim / less selects the app’s own thing

Hold ⇧ while dragging to keep the gesture local, or turn off Settings → Terminal → Mouse → Report mouse to apps.

​
tty7 capture … | head -1 printed a Rust panic

An old build’s behaviour when the reader hangs up. The data you asked for still arrived. On such a build, redirect to a file and slice the file instead of piping into head. Current builds exit 141 on Unix, which is exactly what cat does.

​
Still stuck

Discord

Ask — someone has probably hit it.

Report an issue

Include tty7 doctor output and your platform.