All pages

Docs · Help

Troubleshooting

Availability: macOS, unless a section says otherwise.

Known issues that look like TRMNLY bugs but come from the programs running inside a pane, plus their workarounds — and a few TRMNLY behaviours that get mistaken for failures.

gh auth login fails with "unexpected escape sequence from terminal"

Symptom

$ gh auth login
? Where do you use GitHub?  [Use arrows to move, type to filter]
> GitHub.com
  Other
could not prompt: unexpected escape sequence from terminal: ['\x1b' ']']

The interactive prompt aborts the moment it draws. Other interactive gh commands (gh pr create, gh repo create, …) can hit the same error.

Cause — fixed in TRMNLY 0.1.59. On older builds, use a workaround below.

gh 2.70.0 added light/dark theme detection (via the termenv library). At startup it writes two queries back to back and waits for both replies: an OSC 11 background-color query (\x1b]11;?\x1b\\) and a DSR cursor-position report (\x1b[6n). It uses the cursor report as the sync marker — once that reply arrives it knows the OSC reply is done and drains it. If the cursor report never comes, termenv gives up and leaves the OSC reply sitting in the input buffer. gh's next interactive prompt then reads \x1b ], doesn't understand OSC, and dies with the error above.

Through 0.1.58, TRMNLY never sent that cursor report. Its filter for macOS kernel NFS broadcasts (nfs server …: not responding, which the kernel writes straight to the tty) holds back a trailing partial match across reads so a broadcast split over two reads is still caught. It held back matches as short as one byte — and the phrase starts with n, the same byte \x1b[6n ends with. So the n was withheld pending a next read that, for an idle pty, never arrived: TRMNLY answered the OSC 11 query and then sat there, having never seen the question it was supposed to answer next. 0.1.59 only holds back a partial match that starts at a line boundary, which a cursor-position query never does.

gh's side of this is also a real bug — it should tolerate a terminal that doesn't answer, and it reproduces on urxvt with a transparent background, in Zed's embedded terminal, and under GNU screen. Tracking issue: https://github.com/cli/cli/issues/10830 (still open as of this writing).

Note: setting COLORFGBG does not help — termenv sends the OSC 11 query first and only falls back to COLORFGBG when the query fails, so it doesn't suppress the probe. Neither does NO_COLOR=1, which halves the number of probes but does not stop them.

Workarounds (only needed before 0.1.59)

  • Sign in non-interactively (recommended). --with-token takes a path with no survey prompts to corrupt, and reads the token from gh's own stdin so it never lands in your shell history:

    gh auth login --with-token < mytoken.txt
    # or, interactively: run it, then paste your token and press Ctrl-D
    gh auth login --with-token
    

    Create a token at https://github.com/settings/tokens with at least repo, read:org, and workflow scopes. The command palette has a "GitHub: Sign in with Token" entry that runs this for you.

  • Downgrade gh to 2.69.0 if you need the interactive flows broadly.

  • Watch the upstream issue — a fix to termenv/gh is in progress.

If you hit this same error in some other program on 0.1.59 or later, it is worth checking whether the terminal is answering \x1b[6n at all. From a pane:

python3 -c 'import os,sys,termios,tty,select,time
fd=os.open(os.environ.get("GHOSTTY_PANE_TTY","/dev/tty"),os.O_RDWR)
old=termios.tcgetattr(fd); tty.setraw(fd)
os.write(fd,b"\x1b[6n"); time.sleep(0.3)
r=os.read(fd,64) if select.select([fd],[],[],0.5)[0] else b""
termios.tcsetattr(fd,termios.TCSADRAIN,old); print(repr(r))'

It should print something like b'\x1b[12;1R' immediately. An empty result means a query is being swallowed somewhere.

trmnly in a pane doesn't reach the app

Run trmnly doctor. It prints, on one line each: which binary ran, its version, whether that binary is installed on your PATH, whether it is running inside a TRMNLY pane (surface-scoped commands need --surface when it isn't), how it resolved the surface when $TMUX is set, the socket path it talks to, whether the app answered there, and where the events log is.

The app line is the one to read. reachable means the CLI and the app agree and everything else should work. Otherwise it names the reason: the socket file is gone, the socket is there but nothing answered, or there is no socket and TRMNLY may not be running at all. From inside a pane the app is almost certainly open, so both of the pane-side answers end with If TRMNLY is open, relaunch it — a second copy can delete the first's socket on its way out, and only a relaunch puts it back.

Launching TRMNLY a second time just brings the first one forward

One copy runs per data directory. LaunchServices enforces that for the Dock and Finder; running the binary directly — open -n, or bare trmnly in a pane — is caught by TRMNLY itself, which activates the running copy, writes TRMNLY is already running (pid …) to stderr, and exits.

That is deliberate rather than a failure to start. A second copy would share every file the first is writing and run a second scheduler, Telegram poller and remote-control service against them — enough to stamp the first copy's live reply as cut off and to delete its MCP socket on the way out.

Accessibility or Screen Recording looks revoked after an update

Privacy grants are keyed to TRMNLY's code signature, and TRMNLY's designated requirement names the developer team rather than one certificate. A renewed signing certificate, a new release, and a copy you built yourself all satisfy the same requirement, so a grant given once keeps working — see the Permissions pane in Agent safety.

Two things still ask for action. Updating across 0.1.85 costs one final re-grant, because that is the release the requirement was pinned in. And Screen Recording only takes effect in a freshly launched process, so relaunch TRMNLY after allowing it.

Where crash reports live

Help → Reveal Logs in Finder opens both places at once:

  • ~/Library/Logs/TRMNLY/ — hang samples, crash-<date>.txt write-ups of the crashed thread's stack, and (only if you turn on Settings → Security → Diagnostics → Keep MetricKit crash & hang diagnostics on disk) Apple's MetricKit payloads, which arrive about a day after the event.
  • ~/.local/state/ghostty/crash/*.ghosttycrash — the terminal engine's native crash dumps (event JSON plus a minidump). These carry the crashing thread's backtrace.

When TRMNLY comes back after dying, its notification reads the native dump and names the kind of fault and which part of TRMNLY it was in. Attach the newest files from both folders when reporting a crash, or use Help → Report a Bug or Request a Feature….

Error reports sent to trmnly.dev

When a turn or tool call fails, a store can't be read or saved, the MCP bridge or Remote Control fails, or the app hangs or crashes, TRMNLY sends a short report: which part failed, the error with secrets and your home folder stripped, the model and tool name, and for a hang or crash the app's own stack frames. Never prompts, replies, tool arguments or terminal output. It only goes out while the Mac is signed in to trmnly.dev; repeated failures collapse into one report with a count, and a report held up by a crash or by being offline is sent later.

The switch is Send error reports to trmnly.dev in the agent sidebar's gear menu → Observability → Tool telemetry… (also reachable from Settings → AI Agent → Telemetry (local only) → Open telemetry…). Send test report sends one now, and the line beside it says what the last report did: delivered, refused, retrying, dropped after repeated failures, or not sent because the Mac isn't signed in. The iPhone app has the same switch and button under Settings → Diagnostics.

To see what the agent did on a turn that failed, use Turn traces… — see Agent → When a turn fails. App logs are in the unified log under subsystem com.willschulz.trmnly; use /usr/bin/log show, not zsh's log builtin.