QuickTUI User Guide

About This Guide

Who this guide is for

This guide is for anyone who wants to use an iPhone or iPad to work with AI coding assistants on their computer, such as Claude Code or Codex. You only need to:

• Know how to open a terminal on your computer, and paste and run commands in it.
• Know your computer's user name and login password.

Conventions

• Bold text marks buttons, menus and options in the app or on your computer, for example Next.
• Most code blocks contain commands to run in your computer's terminal: copy the whole line, paste it into the terminal and press Return. When a block shows a config file or a diagram instead, the text says so.
• Text after # is a comment; you don't need to type it.
• "→" means tap one item after another, for example Settings → Shortcuts Bar.
• This guide uses three kinds of callouts:

How to open a terminal on your computer

• macOS: Open Finder → Applications → Utilities → Terminal, or press Command + Space, type "Terminal" and press Return.
• Linux: On most desktops, press Ctrl + Alt + T.
• Windows: Search the Start menu for "PowerShell" and open it.

Chapter 1 Meet QuickTUI

1.1 What QuickTUI does

AI coding assistants (called agents in this guide) usually run in a terminal on your computer. Their tasks can take a long time, and they frequently pause to ask questions or request approval. With QuickTUI you can:

• Keep an eye on your agents from your phone after you leave the computer.
• Answer their questions and approve their actions from your phone.
• Start new agents from your phone and manage several tasks at once.
• Get notified when an agent needs approval or changes state.

Locking your phone or losing the connection won't interrupt your workflow: your agents continue running in the background on the computer.

1.2 How QuickTUI fits together

QuickTUI is made of these parts:

• The QuickTUI app
  Runs on your iPhone or iPad. This is where you watch and work.

• QuickTUI Server
  Runs on your computer as a background service. It securely streams terminal screens and input between your computer and mobile device.

• A terminal session tool: tmux or Herdr
  Runs on your computer and keeps your terminal windows alive. This allows your terminals and agents to keep running after your phone disconnects. QuickTUI calls these tools backends.

  • Herdr: Recommended. If your computer has neither Herdr nor tmux, the QuickTUI Server installer installs Herdr for you. Windows supports Herdr only.
  • tmux: A long-established terminal tool. If tmux is already installed, QuickTUI uses it automatically.

  A single computer can run both backends concurrently.

• QuickTUI Cloud relay (optional)
  A cloud service run by QuickTUI. When your phone can't reach your computer directly, it forwards the encrypted data. It also delivers agent push notifications.

iPhone ──────────────────────────────> Your computer (QuickTUI Server) ──> tmux / Herdr ──> Agent
   │                                        ▲
   └──> (optional) QuickTUI Cloud relay ────┘

1.3 Is your data safe?

• Everything between your phone and your computer is end-to-end encrypted. No third party—including the QuickTUI Cloud relay—can read your data.
• Only paired phones can connect to your computer. After pairing, your phone verifies host identity to prevent spoofing, and the computer accepts only authorized, paired devices.
• The one exception to end-to-end encryption: if you turn on agent notifications, notification summaries pass through QuickTUI Cloud to reach your phone.

1.4 Key terms

• Server: An entry in the app that represents one computer. Server List and Edit Server in the app refer to these entries. This guide uses the word only for these app screens and always in bold; it calls the machine itself "your computer".

• QuickTUI Server: The background program installed on your computer. Its command is quicktui-server. Each computer runs one QuickTUI Server, which appears as one server in the app.

• Pairing: Making a phone a trusted device of a computer. Every device that connects to a computer pairs with it once.

• Backend: The tool on your computer that keeps terminal sessions: tmux or Herdr.

• Workspace: A group of terminal windows. Typically, each workspace maps to an individual project.

• Window: One terminal inside a workspace. Usually, each agent instance occupies a dedicated window. In the app's Switcher, windows are also called sessions.

• Pane: When a window is split into several parts, each part is a pane.

• Backend names: The two backends use different terms for workspaces and windows. This guide standardizes on "workspace" and "window":

  • tmux: a workspace is a session and a window is a window. The Switcher shows "N windows".
  • Herdr: a workspace is a workspace (also called a space) and a window is a tab. The Switcher shows "N tabs".

  In both backends, a window can be split into panes.

• Switcher: The panel in the app for viewing and switching between all workspaces and windows.

• Shortcuts Bar: The strip of buttons and keys at the bottom of the terminal screen. You can stack several of them; the bottom one is the first Shortcuts Bar.

• Input Bar: A text field where you write a whole message and send it to the terminal in one go. It works well for dictation and for sending images and other attachments to an agent.

• IP address: A device's network identifier, such as 192.168.1.10. Dynamically assigned local IPs may change over time.

• Hostname: Your computer's name, such as my-mac.local. On the same Wi-Fi, your phone can find the computer by hostname even when its IP address changes.

• Tailscale: A free networking tool. With it installed on both your phone and your computer, your phone can reach the computer from anywhere through a fixed address (starting with 100.) or its Tailscale machine name.

• Port: A numerical identifier that routes traffic to specific network services on a computer. QuickTUI Server defaults to port 8022.

• SSH: A way to sign in to a computer from another device. QuickTUI can use it to install everything for you from your phone.

Chapter 2 Before You Start

Go through this checklist first.

2.1 Your computer

• It runs macOS, Linux or Windows.
• The agents you want to use are installed and run in a terminal. For example, typing claude in a terminal starts Claude Code. QuickTUI doesn't install agents for you.
• It stays on and doesn't go to sleep. Your phone can't connect to a sleeping computer.

2.2 Your phone

• Install QuickTUI from the App Store.
• Connect your phone to the same Wi-Fi as your computer. This is the easiest way to install and pair the first time; Chapter 4 explains how to connect from elsewhere.

Chapter 3 Install and Pair

3.1 Choose an installation method

Choose the method that best matches your setup:

1. Method A: Install automatically from your phone (recommended)
   For macOS and Linux computers. Enter the computer's address, user name and password on your phone, and the app handles installation and pairing automatically.
2. Method B: Install on the computer, then scan a QR code
   For Windows computers, or computers where you don't want to turn on SSH. If your phone can't scan the QR code, you can copy pairing text from the computer and paste it in the app instead.
3. Method C: Pair through QuickTUI Cloud
   For computers your phone cannot reach directly, such as those inside a corporate network or behind a NAT without a public IP. Requires signing in to QuickTUI with your Apple Account.

3.2 Choose the computer's address

To install and connect, your phone needs to know where to find your computer. You can use three kinds of address: a hostname, a Tailscale address or an IP address.

When you use the QuickTUI Cloud relay (recommended, see 4.3), prefer the hostname. On the same Wi-Fi, your phone then connects to the computer directly, which is fastest. When you leave that network and the direct connection drops, the app switches to the cloud relay automatically.

Without the QuickTUI Cloud relay, use this order of preference:

1. Tailscale address (machine name or IP): Works at home and away. Install Tailscale on your phone and computer first (see 4.4). In mainland China Tailscale can be slow; use the QuickTUI Cloud relay instead.
2. Hostname: Works only on the same Wi-Fi, but keeps working when the computer's IP address changes.
3. IP address: Works only on the same Wi-Fi, and you need to update it when your router gives the computer a new address.

You can use any of these options and switch between address types in the app at any time without re-pairing (see 4.1).

Find the hostname

• macOS: Open System Settings → General → Sharing. Note the Local hostname displayed at the bottom (e.g. my-mac.local).

• Linux: Run this in a terminal:

  hostname

  Append .local to the output name (e.g. my-linux.local).

• Windows: Phones usually can't find Windows computers by hostname. Use a Tailscale address or the IP address.

Find the Tailscale address

If Tailscale is already installed and signed in on your phone and computer, open the Tailscale app on your iPhone and find your computer in the device list. You'll see:

• The Tailscale machine name, such as my-mac. Tailscale provides this name (MagicDNS), and it works whenever Tailscale is connected on your phone.
• An address starting with 100., such as 100.101.102.103.

Either one works. If you haven't installed Tailscale yet, install QuickTUI with the hostname or IP address first and switch later as described in 4.4.

Find the IP address

• macOS: Open System Settings → Wi-Fi, click Details next to the connected network and look for "IP address". Or run:

  ipconfig getifaddr en0

• Linux: Run:

  hostname -I

  The first address listed is typically your local IP.

• Windows: Run ipconfig in PowerShell and look for the "IPv4 Address" of your current network.

Home network addresses usually look like 192.168.x.x or 10.x.x.x.

3.3 Method A: Install automatically from your phone

Step 1: Turn on SSH on your computer

• macOS:
  1. Open System Settings → General → Sharing.
  2. Turn on Remote Login.
• Linux (Ubuntu / Debian): Run:

  sudo apt install -y openssh-server
  sudo systemctl enable --now ssh

Step 2: Install from your phone

1. Open the QuickTUI app. The setup wizard opens on first launch.

   Tip: To add another computer later, tap + in the top-right corner of the Server List.

2. Choose Connect Over SSH — Enable Enhanced Features (Recommended) and tap Next.

3. Enter the computer's details:

   • host: The computer's address (see 3.2): a Tailscale machine name or address (such as my-mac or 100.101.102.103), a hostname (such as my-mac.local) or an IP address (such as 192.168.1.10).
   • port: Leave it at 22.
   • user: Your user name on the computer.
   • auth: Choose pass and enter the computer's login password.

4. Tap Test Connection.

5. The first time you connect, Trust SSH Host Key? appears. Confirm it.

6. When the connection succeeds, tap Next.

7. Choose the install source:

   • In mainland China, choose CN.
   • Elsewhere, choose WORLD.

8. Tap Install and wait. The page shows the progress live; it usually takes a minute or two.

9. When the installation finishes, the app pairs automatically and adds the computer to the Server List.

If automatic pairing fails

If the installation succeeded but automatic pairing failed, check for these common causes:

• Your phone can reach the computer over SSH but not on port 8022, for example because the computer's firewall blocks it.
• You used a hostname or Tailscale machine name that your phone can't resolve right now, for example because Tailscale isn't connected on the phone.

Check both, then pair by scanning a QR code as described in steps 2 and 3 of 3.4.

3.4 Method B: Install on the computer, then scan a QR code

Step 1: Install on the computer

macOS or Linux: Run one of these lines in a terminal:

# In mainland China
curl -fsSL https://dl.quicktui.cn/q.sh | sh

# Everywhere else
curl -fsSL https://quicktui.ai/q.sh | sh

The installer sets everything up. At the end the terminal shows QuickTUI is installed — pair a device and lists ways to show the QR code:

• On a computer with a desktop, type 1 (Browser QR) and press Return. The QR code opens in your browser.
• When you installed over SSH or without a desktop, type 1 (Terminal QR) and press Return. The QR code appears in the terminal.
• If your phone can't scan a QR code, type the number in front of Pairing text and press Return. The terminal shows one line of pairing text; see "Paste pairing text instead" in Step 3.

If it then asks you to choose an address, choose according to item 3 of Step 2 below, then proceed to Step 3 to scan.

Windows:

1. Open Microsoft Store, search for QuickTUI Server and install it. This is QuickTUI Server for Windows.
2. Open QuickTUI Server from the Start menu.
3. If Windows asks whether to allow it through the firewall, choose Allow.
4. QuickTUI Server opens the pairing guide. Follow items 2 and 3 of step 2, then continue with step 3.

Step 2: Show a pairing QR code on the computer

1. Run:

   quicktui-server pairing welcome

   Note: This is the first time this guide runs quicktui-server in a terminal. Here is how to run it on each system; the rest of the guide writes just quicktui-server:

   • macOS and Linux: The program is installed in ~/.local/bin/, and the installer doesn't add that folder to your command path. If the terminal says command not found, either:
     • Type the full path each time, for example ~/.local/bin/quicktui-server pairing welcome, or
     • Run the matching line below, then close and reopen the terminal. After that you can type quicktui-server directly.

       # macOS
       echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
       # Linux
       echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

   • Linux (installed as root): The program is in /usr/local/bin/. Run quicktui-server as root, or put sudo in front, for example sudo quicktui-server pairing welcome.
   • Windows: Run quicktui-server directly in PowerShell.

2. When prompted how to pair, prefer the browser QR if possible. Some terminal fonts or line spacing can distort the QR code and prevent scanning. If your phone can't scan at all, choose Pairing text and follow "Paste pairing text instead" in Step 3.

3. If the guide asks you to choose an address, choose as described in 3.2. Each address is labeled with a type:

   • hostname: the computer's hostname.
   • tailscale: a Tailscale address (starting with 100.).
   • lan: a local IP address.
   • Other types (wireguard, tunnel, wan): addresses on secondary networks; typically not needed for initial setup.

quicktui-server pairing qrcode --browser --public-url http://my-linux.local:8022
quicktui-server pairing qrcode --browser --public-url http://my-mac:8022

Step 3: Scan it on your phone

1. In the app's Server List, tap +.
2. Tap Other ways to connect.
3. Choose Scan a QR Code to Connect a Computer with Enhanced Features and tap Next.
4. Point the camera at the QR code on the computer's screen.
5. On the Pair Server page, tap Pair Server.

Paste pairing text instead

Pairing text carries the same one-time pairing code as the QR code, as a single line you can copy and paste. Use it when the camera can't read the QR code, or when you reach the computer from the phone over SSH.

1. On the computer, run quicktui-server pairing welcome and choose Pairing text, or run:

   quicktui-server pairing qrcode --text

   The terminal shows one line that starts with qtpair:.

2. Copy the whole line and get it onto your phone, for example by copying it in an SSH session on the phone or with your devices' shared clipboard.

3. In the app's Server List, tap +, tap Other ways to connect, choose Paste Pairing Text and tap Next.

4. Paste the text and tap Next. Line breaks and extra spaces from the terminal are removed automatically.

5. On the Pair Server page, tap Pair Server.

3.5 Method C: Pair through QuickTUI Cloud

For computers your phone can't reach directly. Both the computer and the phone connect to QuickTUI Cloud, which forwards the encrypted data.

Step 1: Install on the computer and get a pairing code

1. Install as described in step 1 of 3.4.
2. At the end, the terminal shows QuickTUI is installed — pair a device with a list of options. Type the number in front of Pair through QuickTUI Cloud and press Return.
3. Choose the region: China mainland in mainland China, Global elsewhere. It must match the region you choose on your phone.
4. The terminal shows a pairing code such as ABCD-1234. The code is valid for 15 minutes and allows up to 5 invalid attempts. Keep the terminal open and go to step 2.

quicktui-server pairing welcome

Step 2: Enter the pairing code on your phone

1. In the app's Server List, tap + → Other ways to connect → Pair Through QuickTUI Cloud.
2. Choose the same region as on the computer (China on the phone matches China mainland on the computer, Global matches Global) and sign in with your Apple Account.
3. Enter the pairing code shown on the computer and tap Pair Server.

When pairing succeeds, the computer's terminal shows Paired: followed by your device name.

3.6 Pair another iPhone or iPad

Each device pairs separately. You don't need to reinstall anything:

• For a computer you connect to directly: show a QR code on the computer as in step 2 of 3.4, and scan it on the new device as in step 3.
• For a computer paired through QuickTUI Cloud: run quicktui-server pairing welcome on the computer to get a new pairing code, and enter it on the new device as in step 2 of 3.5.

3.7 Linux: keep the server running after you sign out

On Linux, non-root user services terminate by default when the user session closes (including SSH disconnects). Enable systemd lingering to keep the server running:

loginctl enable-linger

If you see Access denied or a request to authenticate, run this instead:

sudo loginctl enable-linger "$USER"

Check that it worked:

loginctl show-user "$USER" --property=Linger

Linger=yes confirms lingering is enabled.

3.8 Check that everything works

In the app's Server List, tap your computer. If you see the terminal, installation and pairing both worked. Next, see Chapter 5 to start an agent.

If you can't connect, see Chapter 9.

Chapter 4 Connect When You're Away

If you installed with a hostname or a local IP address, your phone connects only when it's on the same Wi-Fi as your computer. This chapter explains how to connect from elsewhere. If you paired through QuickTUI Cloud with Method C (3.5), or installed with a Tailscale address, you don't need to do anything else.

4.1 Two things to know first

1. Changing the address doesn't require pairing again

Your phone reaches your computer through an address such as http://192.168.1.10:8022. You can change it in the app at any time without pairing again:

1. In the Server List, open the computer's Edit Server page.
2. Change scheme, host and port.
3. Tap Test Connection, and save once it succeeds.

Best practice: complete initial pairing on local Wi-Fi, then configure an address for remote access as described in this chapter.

2. Why it's safe without a certificate

QuickTUI encryption operates independently of HTTPS certificates. Even over plaintext http://, end-to-end encryption prevents eavesdropping and host impersonation.

4.2 Choose what fits you

Connection methods ordered by setup complexity:

1. QuickTUI Cloud relay (recommended, see 4.3)
   No network setup, and it works reliably in mainland China. A small amount of traffic is free each month; regular use needs a subscription.
2. Tailscale (see 4.4)
   Install a free app on your phone and computer. No router changes, no domain name. May experience high latency in mainland China.
3. A VPN you already use (see 4.5)
   Such as WireGuard, ZeroTier or a company VPN.
4. Cloudflare Tunnel (advanced, see 4.6)
   If you own a domain managed by Cloudflare.
5. Your own HTTPS reverse proxy (advanced, see 4.6)
   If you already run nginx or Caddy.
6. Router port forwarding (advanced, see 4.6)
   If your home connection has a public IP. Exposes the port directly to the internet; not recommended for beginners.

4.3 QuickTUI Cloud relay (recommended)

The QuickTUI Cloud relay needs no network setup: both your computer and your phone connect out to QuickTUI Cloud, which forwards the encrypted data. Your phone can reach your computer from any network environment.

• Not paired yet: Pair through QuickTUI Cloud with Method C (3.5). The computer then always connects through the relay.
• Already paired directly: Bind the computer to the relay with the steps below. After that, the app connects directly when it can and switches to the relay when it can't.

Agent notifications also require a relay binding (see 7.4).

Bind a paired computer to the relay

1. In the Server List, tap the Cloud button at the top.
2. Choose the right region (China or Global) and sign in with your Apple Account.
3. On the Manage Relay qtrid Slots page (a qtrid identifies a relay slot), choose a qtrid, tap Bind and choose your computer.
4. Open the computer's Edit Server page and set mode to auto.

mode has three options:

• auto: Connect directly when possible, and switch to the relay when not. Recommended.
• direct: Connect directly only.
• relay: Always use the relay.

The Cloud banner at the top of the Server List shows how much relay traffic you've used. The app tells you when it runs out.

4.4 Tailscale

Tailscale joins your phone and computer into a private network. Whether your phone is on Wi-Fi or cellular, it reaches your computer at the same address.

Step 1: Install Tailscale on your computer

1. Go to https://tailscale.com/download, then download and install the desktop app.
2. Open Tailscale and sign in (Google, Apple, Microsoft and other accounts work).

Step 2: Install Tailscale on your iPhone

1. Install Tailscale from the App Store.
2. Sign in with the same account as on the computer.
3. Turn on the connection switch in the Tailscale app. When iOS asks to add a VPN configuration, allow it.

Step 3: Find the computer's Tailscale address

Open the Tailscale app on your iPhone and find your computer in the device list. Use either of these:

• Tailscale machine name, such as my-mac. Provided by MagicDNS, this persistent hostname remains stable across network changes. The fully qualified domain name (e.g. my-mac.tail1234.ts.net) also works.
• Address starting with 100., such as 100.101.102.103.

You can also look them up in a terminal on the computer:

tailscale ip -4      # shows the 100. address
tailscale status     # shows the names and addresses of all devices

Step 4: Point QuickTUI at this address

• QuickTUI Server not installed yet: Install with Method A (3.3) and enter the Tailscale machine name or 100. address as host.

• Pairing with Method B: Generate a QR code with this command on the computer (replace my-mac with your Tailscale machine name), then scan it as in step 3 of 3.4:

  quicktui-server pairing qrcode --browser --public-url http://my-mac:8022

  You can also run quicktui-server pairing welcome and choose an address of type tailscale from the list.

• Already paired: Open the computer's Edit Server page and set:

  • scheme: HTTP
  • host: the Tailscale machine name or address, such as my-mac or 100.101.102.103
  • port: 8022

  Tap Test Connection, and save once it succeeds.

As long as Tailscale remains connected on your iPhone, you can reach your computer from anywhere. You can also use this address at home, eliminating the need to toggle network configurations.

4.5 A VPN you already use

If you already use WireGuard, ZeroTier or a company VPN, and your phone can reach the computer once connected to it, use the computer's address on that VPN.

1. List all of the computer's addresses:

   quicktui-server pairing addresses

   Addresses of type wireguard or tunnel are usually the VPN addresses.

2. If the computer is already paired, open its Edit Server page, set scheme to HTTP, host to this address and port to 8022, tap Test Connection and save once it succeeds.
3. If it isn't paired yet, generate a QR code with this address (replace 10.8.0.2 with the real one) and scan it as in step 3 of 3.4:

   quicktui-server pairing qrcode --browser --public-url http://10.8.0.2:8022

4.6 Cloudflare Tunnel, your own reverse proxy and router port forwarding (advanced)

These advanced options are suited for users who already manage their own domain, reverse proxy, or static public IP. For detailed configuration and pairing instructions, see the Remote access guide on the website:

• Cloudflare Tunnel: Your computer connects out to Cloudflare, and you reach it through an HTTPS address on your own domain. No public IP or router changes needed. Your domain must be managed by Cloudflare.
• Your own HTTPS reverse proxy: If you already run nginx or Caddy, forward a dedicated hostname to QuickTUI Server.
• Router port forwarding: If your home connection has a public IP, forward an external port on your router to port 8022 on your computer. This exposes the server directly to the internet and isn't recommended for beginners.

Chapter 5 Start an Agent

5.1 Create a workspace

When you first connect and there's no workspace yet:

1. Tap the Switcher button on the Shortcuts Bar.
2. Tap + next to the Workspaces heading.
3. In the New Workspace dialog, fill in:
   • Backend: Only needed when both tmux and Herdr are enabled on the computer. If unsure, keep the default setting.
   • CWD: The workspace's default folder, usually your project folder.
   • Workspace name: Optional; a name is generated if you leave it empty.
4. Tap Create.

When the computer has no backend

If the app says The server is connected, but no session backend is available, the computer has no working tmux or Herdr, for example because downloading Herdr failed during installation. You can install one from the app:

1. Tap Install Herdr (recommended) in the panel. On macOS and Linux you can choose Install tmux instead; on Windows only Herdr is available.
2. Wait for the installation. You can leave the page meanwhile; the installation continues on the computer.
3. When it succeeds, the app reconnects automatically.

If the installation fails, the panel shows the reason and a command you can run on the computer yourself. After installing it manually, return to the app and tap retry. There's no need to restart QuickTUI Server.

5.2 Start an agent with the Agent Wizard

The Agent Wizard opens a new window in the current workspace and starts the agent in it.

1. Tap the Agent Wizard button on the Shortcuts Bar.
2. Choose the Agent: swipe sideways and tap the one you want. An agent name shown in a warning color means it wasn't found on the computer (see 5.4).
3. Set the Configuration (the defaults are fine):
   • Preset: A saved combination of model and effort.
   • Model / Effort: Shown only for some agents.
   • Mode: Usually Default. For long unattended tasks, consider YOLO mode (see warning below).
4. Choose the working directory: tap the path to pick a recently used folder, or tap the folder button next to it to browse.
5. Session title (optional): Name the task so you can find it later.
6. Tap Launch.

The app switches to the new window and the agent starts. The wizard remembers your selections for subsequent launches.

5.3 Start an agent from the terminal

In addition to the Agent Wizard, you can launch agents directly by typing their command in the terminal:

claude

5.4 When the Agent Wizard can't find an agent

Because QuickTUI Server runs as a background service, its default environment variables may not resolve agent binaries installed in non-standard locations.

1. See which programs QuickTUI Server finds:

   quicktui-server doctor

2. Run which claude (on Windows, Get-Command claude in PowerShell; replace claude with your agent's command) and note the full path it prints.
3. Open the config file in any text editor (on macOS and Linux you can run nano ~/.config/quicktui-server-v2/config.toml; for other systems see Appendix B) and add at the end:

   [agent_bins]
   claude = "/opt/homebrew/bin/claude"

   Replace the path with the one from step 2.

4. Save, then restart: quicktui-server service restart.

5.5 Agent status detection (hooks)

QuickTUI can show whether an agent is working or waiting for you, and notify you when needed. This relies on hooks that the installer adds to each agent's configuration. Usually you don't need to do anything, with two exceptions:

• Codex: Type /hooks in Codex and trust the hooks QuickTUI added.
• OpenCode: Restart OpenCode once after installing.

Chapter 6 Work with Your Agents

Your agents run in the terminal on your computer. The app shows that terminal, and what you type goes straight to the agent.

6.1 The terminal screen

• Top bar:
  • Left: back to the Server List, and full screen.
  • Middle: the current workspace's name.
  • Right: Files and Port Forwarding. Files opens the file manager to browse and transfer files on the computer; Port Forwarding makes a port on the computer (such as a web app you're developing) available on your phone. Both are outside the scope of this guide.
• Terminal: The large area in the middle is your computer's terminal.
• Shortcuts Bar: The strip at the bottom. Its default buttons, from left to right:
  • Settings, Switcher, Files, Agent Wizard
  • Custom Keyboard, Clipboard History
  • Command Palette, Input Bar, Show / Dismiss Keyboard

Swipe sideways when the bar doesn't fit on screen. In Settings → Shortcuts Bar you can add up to 3 more bars with keys you use often, such as Esc, Tab, arrows and Ctrl combinations. Holding down a key repeats the keystroke.

6.2 Send instructions

The Input Bar is the best way to send longer instructions:

1. Tap the Input Bar button on the Shortcuts Bar.
2. Compose your prompt or command in the Input Bar with multi-line support.
3. Tap Send to transmit the complete multi-line text block cleanly to the agent.
4. Tap the paperclip icon in the Input Bar to attach images or files for the agent.

Other ways to type:

• System keyboard: Sends keystrokes immediately as typed; ideal for brief commands.
• Custom keyboard: A keyboard made for terminals, with Esc, Ctrl, arrow keys and more.
• Command Palette: Save recurring commands for one-tap execution. Configure them in Settings → Manage command palette.
• Clipboard History: Quickly paste previously copied text snippets.

6.3 Respond to an agent

• When the agent offers numbered options: Type the corresponding number and press Return, or navigate with arrow keys and press Return.
• Interrupt or stop the agent: Press Esc (Claude Code) or Ctrl + C. Both keys can go on a Shortcuts Bar.
• Slash commands: Type them just as on the computer, for example /clear.
• Approve from a notification: With agent notifications on (see 7.4), you get a notification when an agent asks for permission. Touch and hold it to choose Approve or Reject without opening the app.

6.4 Read and copy output

• Scroll back: Swipe up and down on the terminal.
• Copy text:
  1. Touch and hold the text; when the magnifier appears, drag to adjust the selection.
  2. Tap the floating Copy button.
  3. When terminal line wrapping breaks continuous output across lines, tap Smart Copy to merge it into a single line before copying.

6.5 Leave and come back

You can freely lock your device, switch apps, or disconnect; computer-side agents run uninterrupted. Returning to QuickTUI automatically reconnects and synchronizes the terminal display.

Chapter 7 Manage Tasks with the Switcher

When running multiple agent tasks concurrently, use the Switcher to monitor status and toggle between them.

7.1 Open and close the Switcher

• Open: Tap the Switcher button on the Shortcuts Bar.
• Close: Tap the close button in the top-right corner, or swipe down on an empty area.

7.2 Read the Switcher

The Switcher has two parts, top to bottom:

Servers
 [My Mac ✓] [Office Linux]             ← tap to switch to another computer

Workspaces  ⊕                          ← new workspace
  api-refactor   tmux · 3 windows  …   ← tap to expand or collapse; … opens the menu
    ✓ 1 claude    (Claude icon) (Working)
      2 codex     (Codex icon)  (Blocked)
      3 shell
  docs           herdr · 2 tabs    …

• Servers: Every computer you've added. The checkmark indicates the active computer; tap any other to switch.
• Workspaces: Displays the underlying backend (tmux or Herdr) and window count ("N windows" for tmux, "N tabs" for Herdr). Tap to expand or collapse the window list. A workspace containing only a single window opens directly upon tapping.
• Windows: The checkmark indicates the active window. Tap another window to switch to it. Windows running an agent show the agent's icon and status.
• Panes: When a window is split, its panes are listed below it, and you can switch straight to one.

7.3 Agent status

The status icon next to a window tells you what each agent is doing:

• Working: The agent is actively executing tasks; no input required.
• Blocked: The agent is paused awaiting permission or user input. Switch to this window to respond.
• Done: The current execution round finished. Review results and assign follow-up tasks.
• Idle: The agent is inactive.

7.4 Get agent notifications

With notifications on, you know which agent needs you without opening the app.

Requirements:

• The computer is bound to the QuickTUI Cloud relay (see 4.3) or was paired through QuickTUI Cloud with Method C (3.5).
• Agent hooks are working (see 5.5).
• Notifications for QuickTUI are allowed in the iPhone's Settings → Notifications → QuickTUI.

Setup:

1. In the Server List, open the computer's Agent Notifications page.
2. Turn on Notify this device.
3. Choose which notifications you want: Approval required, Task complete, Agent error, Session ended.
4. (Optional) Choose what notifications include: Include agent, Include project, Include summary, Include session name.

7.5 Recommended task workflow

One workspace per project, one window per task.

1. Create a dedicated workspace for each project, setting its CWD to the project root (see 5.1).
2. Launch each task via the Agent Wizard, entering a descriptive name in Session title (e.g. fix-login).
3. Once tasks are dispatched, you can step away. When a notification arrives or you open the Switcher, prioritize Blocked sessions.
4. When a task finishes and results are verified, close the window (see 7.7).

7.6 Switch quickly

Swipe sideways on the terminal to move to the previous or next window without opening the Switcher.

In Settings → Horizontal swipe destination you choose what a swipe moves between:

• Workspace: Switch between workspaces.
• Session: Switch between windows.
• Pane: Switch between panes.
• Session+Pane: Switch across both windows and panes (default).

7.7 Create, rename and close

• New workspace: Tap + next to the Workspaces heading.
• New window in a workspace: Tap … on the right of the workspace → New session. The app switches to it.
• Start an agent in a workspace: Tap … on the right of the workspace → Agent Wizard.
• Rename or close a workspace: Tap … on the right of the workspace, or touch and hold it.
• Rename or close a window: Touch and hold the window. This works only for windows in the current workspace.

Chapter 8 Maintenance

8.1 Update QuickTUI Server

Recommended (macOS and Linux): run the install command again. The same command you installed with updates to the latest version. Run one of:

# In mainland China
curl -fsSL https://dl.quicktui.cn/q.sh | sh

# Everywhere else
curl -fsSL https://quicktui.ai/q.sh | sh

Reinstalling keeps your paired devices, the server identity, the QuickTUI Cloud relay binding and your settings. No re-pairing is required.

Other ways to update:

• From your phone: When a new version is available, an upgrade button appears next to the computer in the Server List. Tap it and follow the prompts.
• With a command (macOS and Linux): quicktui-server upgrade install.
• Windows: Microsoft Store updates it automatically.

8.2 Manage paired devices

When a phone is lost or retired, remove its pairing:

1. List all paired devices:

   quicktui-server pairing devices list

2. Find the device, note its device_id, and run:

   quicktui-server pairing devices revoke <device_id>

   Replace <device_id> with the real ID.

A revoked device is disconnected within 5 minutes and cannot reconnect without re-pairing.

8.3 Uninstall

For uninstall commands and steps, including Windows and complete removal, see Uninstall on the website's install page.

Uninstalling stops QuickTUI Server but preserves pairing credentials, allowing hassle-free reinstallation without re-pairing. tmux, Herdr and your agents remain untouched.

Chapter 9 Troubleshooting

Causes and fixes for common problems are collected in the website's FAQ. Open the entry that matches what you see:

• The app says "Local Network Access Required"
• Can't connect — connection refused
• I can connect at home but not when I'm away
• I can't connect through Tailscale
• Connecting by hostname fails, but the IP address works
• The app says no session backend is available
• On Linux, the server stops after I sign out
• The app says this device is no longer paired with the server
• Through a tunnel or reverse proxy, the app shows an HTTP status code
• Another QuickTUI server is listening on the port
• The Agent Wizard shows an agent in a warning color
• The app shows no live status for my agents
• How do I view server logs?

Appendix A: Commands

For every quicktui-server command and option, see Command reference on the website's install page. If quicktui-server isn't found, see the note in step 2 of 3.4.

Appendix B: File Locations and Configuration

• Where the program, config directory and background service live on each system: see Install locations on the website's install page.
• Every setting in config.toml (including addr, trusted_proxies, session_backends and [agent_bins]): see Configuration on the install page.

After editing the config file, run quicktui-server service restart for the changes to take effect.