q quicktuiv1 Get the App

FAQ

Frequently asked questions

Full FAQ grouped by topic: installation, service, sessions, mobile apps, and the browser.

Installation

Q.01 — Checksum verification failed during install.

Usually the download was interrupted or corrupted — re-run the installer. If it persists, release assets may have just been updated; wait a few minutes and retry.

Also verify nothing is intercepting HTTPS traffic (e.g. a corporate proxy).

Q.02 — tmux is not installed or the version is too old.

macOS / Linux: the session backend is tmux 3.2 or later. The installer does not install tmux — install it yourself with your package manager (brew, apt, yum, dnf, …) and re-run the installer. If install or service registration fails with “tmux not found” or a version error, upgrade tmux first.

Optional override: set the installer environment variable QUICKTUI_TMUX_BIN to an absolute path, or set the TOML key tmux_bin. Service registration may write the discovered absolute path into config so launchd/systemd can find it outside a normal shell PATH.

Windows: the default backend is qscn (qscreen), not tmux. The installer downloads and installs qscn automatically under %LOCALAPPDATA%\QuickTUI\ and writes session_backend = "qscn" plus qscn_bin. You do not need tmux on Windows.

Q.03 — What happens when I re-run the installer?

It detects the existing server binary and switches to upgrade mode: stops the service, stages and version-checks the new binary, atomically swaps it into place, and rolls back on failure. Existing config keys (address, TERM, LANG, session backend, tmux_bin / qscn_bin, and others) are preserved.

Binary locations: macOS/Linux ~/.local/bin/quicktui-server; Windows %LOCALAPPDATA%\QuickTUI\quicktui-server.exe.

Server & Service

Q.04 — What can I configure in the config file?

Default path: ~/.config/quicktui-server-v2/config.toml (on Windows: %USERPROFILE%\.config\quicktui-server-v2\config.toml). Installed services start with serve --config pointing at that file. A normal quicktui-server serve process also loads this file (or the path from --config). Priority for serve: CLI flag > config file key > built-in default. Process environment variables are not used for serve configuration (only a few side paths such as service install use the process env).

Common keys:

After editing, restart the service:

# macOS
launchctl kickstart -k gui/$(id -u)/ai.quicktui

# Linux
systemctl --user restart quicktui

# Windows — prefer the full path (quicktui-server is not always on PATH)
& "$env:LOCALAPPDATA\QuickTUI\quicktui-server.exe" service restart

Q.05 — How do server upgrade and restart work?

Two paths:

Re-run the installer — atomic swap, rollback on failure, config preserved. On Windows this is the supported upgrade path for the binary.

Server self-update (macOS / Linux) — the app/API path (POST /v2/api/update) downloads and replaces the binary but does not auto-restart; restart from the app/browser, call POST /v2/api/restart, or restart the service. CLI quicktui-server upgrade install upgrades and then restarts an installed service. On Windows, upgrade install is not supported — re-run the installer (irm https://quicktui.ai/q.ps1 | iex).

Update / restart / shutdown are serialized: a new update is rejected if a restart is in progress, and vice versa.

Check status:

# macOS / Linux
quicktui-server upgrade check

# Windows
& "$env:LOCALAPPDATA\QuickTUI\quicktui-server.exe" upgrade check

Q.06 — Can I validate the environment without installing?

Yes — run environment preflight checks without installing or configuring QuickTUI:

# macOS / Linux
curl -fsSL https://quicktui.ai/q.sh | sh -s -- check

# Windows (PowerShell)
& ([scriptblock]::Create((irm https://quicktui.ai/q.ps1))) check

Q.07 — How do I pair another device?

Run quicktui-server pairing qrcode on macOS/Linux, or & "$env:LOCALAPPDATA\QuickTUI\quicktui-server.exe" pairing qrcode in Windows PowerShell, then scan the short-lived QR from the native app. On a desktop, add --browser for a pixel QR; use --select-address to choose a detected address or --debug-addr https://your.domain behind a TLS proxy. This CLI flow currently supports new-device pairing for native apps that can scan the QR; it does not provide a supported full-payload export for new Web or Desktop pairing. Pairing registers a device public key and pins the server identity; it does not create or reveal a root token.

Q.08 — Can't connect — connection refused.

First check the service:

# macOS
launchctl print gui/$(id -u)/ai.quicktui

# Linux
systemctl --user status quicktui

# Windows (Scheduled Task; if missing, may be HKCU Run fallback)
schtasks /Query /TN QuickTUI
reg query "HKCU\Software\Microsoft\Windows\CurrentVersion\Run" /v QuickTUI

Prefer service restart / service uninstall with the full path under %LOCALAPPDATA%\QuickTUI\ — they cover both Scheduled Task and Run-key modes. If you skipped service registration, start quicktui-server with the same config and address (or pass serve --debug-addr). If it's running, make sure your firewall or tunnel allows the port from addr.

Q.09 — Text rendering is garbled when TERM=xterm-ghostty.

On the tmux backend, server-side tmux won't render correctly when TERM=xterm-ghostty is forwarded — Ghostty's own terminfo isn't a fit for tmux inside the remote session.

Use a widely supported TERM instead. In the config file:

term = "xterm-256color"

Then restart the service. For a one-off serve command:

quicktui-server serve --term xterm-256color

Q.10 — PTY spawn failed / internal server error when opening a session.

QuickTUI could not launch or attach the session backend (tmux or Herdr on macOS/Linux, qscn on Windows). Check logs (see Q.11). On tmux: if tmux_bin is set, it must be an absolute path to a real tmux binary; also verify term and lang. On Windows: confirm qscn_bin points at a working qscn.exe (re-run the installer if needed).

Q.11 — How do I view server logs?

# macOS
tail -f ~/Library/Logs/QuickTUI/stdout.log \
        ~/Library/Logs/QuickTUI/stderr.log

# Linux
journalctl --user -u quicktui -f

# Windows — no dedicated log files (Scheduled Task or HKCU Run).
# Prefer service restart (covers both). Optional status checks:
schtasks /Query /TN QuickTUI /V /FO LIST
reg query "HKCU\Software\Microsoft\Windows\CurrentVersion\Run" /v QuickTUI
& "$env:LOCALAPPDATA\QuickTUI\quicktui-server.exe" service restart
# Foreground (after stopping the installed service):
& "$env:LOCALAPPDATA\QuickTUI\quicktui-server.exe" service uninstall
& "$env:LOCALAPPDATA\QuickTUI\quicktui-server.exe" serve --config "$env:USERPROFILE\.config\quicktui-server-v2\config.toml"

On Windows, prefer service restart over raw schtasks /End then /Run — the server waits for the old process to exit so the port is free. After a temporary foreground run, re-install the service with service install using the same full path.

If you started quicktui-server manually, output appears in the terminal where you launched it.

Q.12 — How do I change the listen address or port?

Service: edit addr in the config file, then restart (see Q.04).

Manual:

# macOS / Linux
quicktui-server serve --debug-addr 0.0.0.0:9000

# Windows
& "$env:LOCALAPPDATA\QuickTUI\quicktui-server.exe" serve --debug-addr 0.0.0.0:9000

At install time:

# macOS / Linux
curl -fsSL https://quicktui.ai/q.sh | sh -s -- install --channel stable \
  --addr 127.0.0.1 --port 9000

# Windows (PowerShell)
& ([scriptblock]::Create((irm https://quicktui.ai/q.ps1))) install --channel stable --addr 127.0.0.1 --port 9000

--addr accepts an IPv4 address, a hostname, or an http(s)://host:port URL (the scheme is only a writing convenience — the server still listens over plain HTTP). An IPv6 literal must be bracketed and carry its own port, for example --addr "[::1]:9000"; a bare ::1 is rejected. --port only applies when --addr has no port yet.

Q.13 — How do I uninstall QuickTUI?

# macOS / Linux
curl -fsSL https://quicktui.ai/q.sh | sh -s -- uninstall

# Windows (PowerShell)
$qps1 = "$env:TEMP\q.ps1"; irm https://quicktui.ai/q.ps1 -OutFile $qps1
powershell -File $qps1 uninstall

Uninstall only stops and unregisters the service (launchd / systemd user unit / Windows Scheduled Task QuickTUI or HKCU Run fallback) — it leaves the binary and your local state on disk. For a complete clean-up afterwards, also remove:

Deleting the config directory permanently discards the server identity and all paired devices, so every client must pair again.

Q.14 — macOS file browser hangs on Desktop / Documents / Downloads.

File browsing is gated by files_enabled in the config (default off until you enable Files in the app, which writes true via the server API). If Files is disabled, enable it in the client first.

macOS protects Desktop, Documents, Downloads, iCloud Drive, and other system folders via TCC (Transparency, Consent, Control). The QuickTUI service runs as a background launchd agent and cannot trigger the system consent dialog, so accesses to those folders hang silently until the request times out.

Fix — grant Full Disk Access to the quicktui-server binary:

  1. Open System Settings → Privacy & Security → Full Disk Access.
  2. Click the + button. In the file picker, press Cmd+Shift+G and enter ~/.local/bin, then select quicktui-server.
  3. Make sure the toggle next to quicktui-server is enabled.
  4. Back in the QuickTUI client, tap Recheck on the warning banner. No service restart needed.

If Recheck still fails, restart the service:

launchctl kickstart -k gui/$(id -u)/ai.quicktui

Why no consent dialog appears: macOS only shows the TCC consent prompt for processes launched with a UI context (Finder, Terminal, Dock). Background launchd agents have no UI, so the prompt is never displayed and the OS silently blocks until manually authorized.

Q.15 — Linux file browser shows "permission denied" or returns 403.

File browsing is gated by files_enabled (default off until enabled from the app). If the client shows Files as disabled, enable it there first so the server writes files_enabled = true.

The QuickTUI service runs under your user (typically systemd --user) and can only read paths your user has POSIX read+execute on. Common causes:

Fix steps:

  1. Run ls -ld /full/path/to/dir on the failing path and every parent. Confirm the user running quicktui-server has r-x on dirs and r-- on files.
  2. Identify which user the service runs as: systemctl --user show quicktui -p MainPID, then ps -o user= -p <PID>.
  3. Adjust permissions: chmod o+rx /path for shared paths, or use ACLs (setfacl -m u:<user>:rx /path) for selective access.
  4. If SELinux blocks access, add a file context label or use audit2allow to generate a policy module — see your distro's SELinux docs.
  5. Tap Recheck in the client. No service restart required.

If still failing, check logs: journalctl --user -u quicktui -f while reproducing.

Sessions (tmux / Herdr / qscn)

Q.16 — My session list is empty.

QuickTUI lists sessions from the configured backend (tmux or Herdr on macOS/Linux, qscn on Windows). With tmux or qscn, create one from the app or browser with New Session. On macOS/Linux you can also create a named tmux session on the machine:

tmux new-session -s mysession

On Windows, prefer New Session in the app; the backend is qscn, not tmux.

With the Herdr backend, New Session is not available: QuickTUI only lists, focuses, and attaches to Herdr sessions, so start or create the workspace in Herdr itself and it will appear in the list.

Q.17 — tmux scrollback shows duplicated / misaligned text after running Claude Code.

Applies when the session backend is tmux (typical on macOS/Linux).

Symptom. After interacting with Claude Code (or similar TUI tools like OpenAI Codex CLI, aider) inside a tmux pane, scrolling back through tmux history shows duplicated frames, misaligned columns, or fragments of older render passes. Restarting the QuickTUI service does not fix the desktop tmux side — only tmux clear-history clears it.

Cause. Claude Code's TUI is built on the Ink rendering library. When the rendered region exceeds the terminal viewport (or on every full-viewport repaint), Ink's render loop emits CSI 3 J ("Erase Saved Lines") and re-paints the whole screen on the main screen buffer — without DECSET 2026 (synchronized output) bracketing. tmux processes the partial frames and writes them into pane scrollback. Subsequent SIGWINCH / resize events compound this: each intermediate width pushes another stale frame into history. Upstream tracking issues:

Fix. Run Claude Code in fullscreen mode — it switches to the alternate screen buffer (like vim / htop) and never touches scrollback. Requires Claude Code v2.1.89+:

/tui fullscreen

Versions v2.1.89 — v2.1.109 use the environment variable instead:

CLAUDE_CODE_NO_FLICKER=1 claude

Recovering existing corrupted scrollback. The garbled bytes are already inside tmux's pane history; only clearing it removes them:

tmux clear-history

Then re-launch Claude Code in fullscreen mode to prevent recurrence. The QuickTUI client also pops a hint banner the first time you select a pane that is running Claude Code (or another known TUI tool) on the main screen.

Q.18 — Garbage like 11;rgb:2828/2c2c/3434 keeps appearing in a terminal app's input box.

Most often seen with the tmux backend when multiple clients attach to the same session.

Symptom. When multiple clients (for example a local terminal plus the QuickTUI app or browser) attach to the same tmux session, the terminal app's input box repeatedly fills with garbage like 11;rgb:2828/2c2c/3434 — sometimes several in a row.

Cause. Some terminal apps auto-detect your color theme by sending OSC 10/11/12 escape queries ("what are the current foreground / background / cursor colors?"). tmux forwards the query to the outer terminal and routes the reply back into the pane. With several clients attached, that reply can land after the app's short parsing window for that reply has already closed, so the app treats the raw escape bytes as literal keystrokes and drops them straight into its input box. This is an application-side bug, not a QuickTUI issue — for example Claude Code tracked it as #12910 — OSC terminal color query responses leak into input buffer.

Fix.

  1. Give the affected app a fixed theme instead of auto-detect. In Claude Code, run /theme and pick a fixed light or dark value.
  2. For other TUI tools, turn off automatic terminal color / theme detection the same way.
  3. Optional: reduce escape-sequence fragmentation under tmux by adding this to ~/.tmux.conf:
    set -s escape-time 100

Q.19 — Does QuickTUI work with Herdr?

Yes, on macOS and Linux, with Herdr v0.8.0 (the currently verified release). Set the backend in the config file and restart the service:

session_backend = "herdr"
herdr_bin = "/absolute/path/to/herdr"

Use session_backends = "tmux,herdr" to list both tmux and Herdr sessions. QuickTUI lists, focuses, and attaches to Herdr sessions; create and manage the workspaces in Herdr itself. As of August 2026 the Herdr backend ships in the preview server channel (install --channel preview). The iPhone, iPad, and browser clients only connect to the QuickTUI server, never to Herdr directly. See tmux and Herdr on iPhone & iPad.

Mobile Apps & Browser

Q.20 — How does device authentication protect my connection?

QuickTUI uses device pairing instead of a root access token or browser token login. A short-lived pairing code registers the client's public key and a pinned server fingerprint. Every later connection proves possession of that device's private key inside the current encrypted handshake with transcript-bound device_pop_v1; the proof cannot be replayed on another E2E connection.

All business traffic uses the same pinned client-to-server E2E tunnel. A direct connection carries it end to end. QuickTUI Relay only forwards opaque encrypted frames and cannot read terminal, file, or Agent traffic. Browser clients store a non-exportable P-256 device key in IndexedDB only on an HTTPS or loopback origin such as http://localhost:8022; remote plain-HTTP origins fail closed.

Profiles created with the retired root token must pair again. A legacy per-device bearer may be converted once inside a pinned E2E tunnel; the client then re-authenticates with device_pop_v1 before removing the old credential. List or revoke devices with quicktui-server pairing devices list and quicktui-server pairing devices revoke <device_id>; on Windows PowerShell use the executable at $env:LOCALAPPDATA\QuickTUI\quicktui-server.exe. A revoked client returns to pairing.

Q.21 — Can I connect over the internet?

Yes. Make the machine reachable from the internet — via VPN, reverse proxy with TLS, a tunnel such as Tailscale or Cloudflare Tunnel, or the optional QuickTUI Relay subscription (cloud relay when you cannot expose the host; bind with the app or, on the machine, quicktui-server config relay set <qtrid> <ws-endpoint> — on Windows use the full path under %LOCALAPPDATA%\QuickTUI\). The outer listener speaks plain HTTP on 8022 on the machine, while paired business traffic remains inside the client-server E2E tunnel. Do not expose raw port 8022 to the public internet without TLS in front. If you terminate TLS on a reverse proxy or tunnel, point it at http://127.0.0.1:8022 and use the public HTTPS hostname in the app, usually without an explicit port. :443 is equivalent; do not put :8022 on the public HTTPS URL.

When generating a pairing QR behind TLS or a tunnel, pass the public base URL only into the QR (capability probe still uses the local listen address from config):

# macOS / Linux
quicktui-server pairing qrcode --debug-addr https://your.domain

# Windows
& "$env:LOCALAPPDATA\QuickTUI\quicktui-server.exe" pairing qrcode --debug-addr https://your.domain

Pairing codes are short-lived credentials; do not post a QR or pairing payload in a public channel.

Q.22 — The app or browser shows "Session not found".

This comes directly from the server — the session was closed, renamed, or the session backend (tmux / Herdr / qscn) is not running.

Refresh the session list, then open an existing session. With tmux or qscn you can also create a new one with New Session; with Herdr, start or recreate the workspace in Herdr itself, then refresh the list.

Q.23 — What data is sent with Agent notifications, and how do I turn them off?

Agent notifications are opt-in per device. The operating system permission and that device's notification registration are separate controls. Each QuickTUI server also has server-wide preferences for enabling notifications to registered devices, selecting approval request / task complete / error / session ended categories, and choosing optional text fields.

The default notification text only identifies the event category. You can additionally allow the Agent type, project name, session name, and a task or error summary. There are no fields for full terminal output, source code, credentials, or full prompts or Agent responses; selected names and summaries can still contain text supplied by you or an Agent.

Delivery and notification opening still need route-only values such as the bound device ID, routing mode, category, notification ID/revision, collapse ID, sent time, and Agent runtime/session/interaction references or compact locators. These are not display fields and remain independent of the text switches. An internal request ID used for Relay retries and deduplication is not sent to the device. Your server stores its preferences and device registrations locally, then sends the selected text, route-only values, and device push token through QuickTUI Relay to APNs or FCM. Relay does not persist push tokens or payloads; its bounded, short-lived retry state includes Relay and request identifiers, a request hash, lifecycle metadata, and the response, but not the push token or notification payload. APNs delivers an iOS alert, while FCM sends a data-only message that QuickTUI processes before displaying on Android.

To stop notifications, revoke the operating system permission, disable that device's registration, or change the server-wide preferences. Removing the last local profile using a paired-device credential requests revocation of that credential's remote push registration. A notification already accepted by APNs or FCM may still arrive. See the Privacy Policy for the full disclosure.

Related