q quicktuiv1 Get the App

FAQ

Frequently asked questions

Full FAQ grouped by topic: installation, service, sessions, and the iOS app & 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 QUICKTUI_TMUX_BIN to an absolute path of a valid tmux binary (in the environment when installing the service, or in the config file). When the service is registered, QuickTUI may also 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 QUICKTUI_SESSION_BACKEND=qscn plus QUICKTUI_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 the new binary, sanity-checks --version, atomically swaps it into place, and rolls back on failure. Existing config keys (token, address, TERM, LANG, session backend, QUICKTUI_TMUX_BIN / QUICKTUI_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/config (on Windows: %USERPROFILE%\.config\quicktui\config). Installed services start with --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" --restart-service

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-server upgrades and then restarts an installed service. On Windows, --upgrade-server 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 --check-upgrade

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

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 — QuickTUI says "token is required".

Ensure the config file contains a non-empty token:

QUICKTUI_TOKEN=…

Default path: ~/.config/quicktui/config (Windows: %USERPROFILE%\.config\quicktui\config). Or pass --token on the command line. Serve uses flag > config file; setting only a process environment variable is not enough for a normal quicktui-server process.

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 --restart-service / --uninstall-service 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 a config that has the same token and address (or pass --token / --addr). If it's running, make sure your firewall or tunnel allows the port from QUICKTUI_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:

QUICKTUI_TERM=xterm-256color

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

--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 on macOS/Linux, qscn on Windows). Check logs (see Q.11). On tmux: if QUICKTUI_TMUX_BIN is set, it must be an absolute path to a real tmux binary; also verify QUICKTUI_TERM and QUICKTUI_LANG. On Windows: confirm QUICKTUI_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 --restart-service (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" --restart-service
# Foreground (after stopping the installed service):
& "$env:LOCALAPPDATA\QuickTUI\quicktui-server.exe" --uninstall-service
& "$env:LOCALAPPDATA\QuickTUI\quicktui-server.exe" --config "$env:USERPROFILE\.config\quicktui\config"

On Windows, prefer --restart-service 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 --install-service 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 QUICKTUI_ADDR in the config file, then restart (see Q.04).

Manual:

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

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

At install time:

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

# Windows (PowerShell)
& ([scriptblock]::Create((irm https://quicktui.ai/q.ps1))) --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 access token and paired devices.

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

File browsing is gated by QUICKTUI_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 QUICKTUI_FILES_ENABLED (default off until enabled from the app). If the client shows Files as disabled, enable it there first so the server writes QUICKTUI_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 / qscn)

Q.16 — My session list is empty.

QuickTUI lists sessions from the configured backend (tmux on macOS/Linux, qscn on Windows). If none exist yet, 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.

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

iOS App & Browser

Q.19 — What is the access token?

A secret stored as QUICKTUI_TOKEN — it protects the server HTTP API and browser login. You set it during installation (or later with the installer --token / --rotate-token flags). Find it on your machine:

# macOS / Linux
cat ~/.config/quicktui/config
# or
quicktui-server --dump-token

# Windows (PowerShell)
Get-Content $env:USERPROFILE\.config\quicktui\config
# or
& "$env:LOCALAPPDATA\QuickTUI\quicktui-server.exe" --dump-token

Browser client: open http://<host>:8022 and paste the access token once when prompted.

Native app pairing: do not paste the access token. On the machine run:

# macOS / Linux
quicktui-server --pair-qrcode
# optional: --browser

# Windows
& "$env:LOCALAPPDATA\QuickTUI\quicktui-server.exe" --pair-qrcode

Then scan in the app. Pairing uses a short-lived pairing code inside the QR, not the access token. On Windows the install directory is usually not on PATH — use the full path above.

Q.20 — 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 --update-config-relay <qtrid> <ws-endpoint> — on Windows use the full path under %LOCALAPPDATA%\QuickTUI\). QuickTUI itself speaks plain HTTP on 8022 on the machine. 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 --pair-qrcode --addr https://your.domain

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

Keep the access token secret for browser login; do not paste pairing codes or tokens into public channels.

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

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

Refresh the session list, then open an existing session or create a new one.

Related