What PocketTUI can do

How to work with PocketTUI

1. Finding the backend from inside a tmux session

Rules for the token:

• Read it only when a route in section 4 is needed, and never print it to the pane, a log, or a commit. Every device attached to the session sees the pane, and the code is the only thing guarding a full shell.
• A wrong token answers 401 {error:"bad token", hint} and counts toward the per-IP backoff (5 free tries, then doubling delays up to 300 s, app.py:296-368). Do not retry in a loop.
• Mutating session routes share a limit of 20 calls per 60 s per IP (RATE_SESSION_MUTATE, app.py:410).
• Routes that take dev resolve to that device's own grouped view. An agent has no device name, so leave dev out and the base session is used.

Minimal probe:

PORT=$(python3 -c 'import json;print(json.load(open("'"$HOME"'/pockettui/runtime.json"))["port"])' 2>/dev/null || echo 5560)
curl -s http://127.0.0.1:$PORT/.well-known/pockettui
curl -s -H "X-PocketTUI-Token: $(cat ~/pockettui/.token)" http://127.0.0.1:$PORT/api/version

2. Discovery

GET /.well-known/pockettui: no token. Returns {"product":"pockettui","version":"<VERSION or "">"} and nothing else (no hostname, port, paths or capabilities). The phone and the installer use it as a reachability probe (app.py:1268-1283).

GET /api/version: token. Returns {"version": str, "host": socket.gethostname(), "capabilities": {flag: bool}} (app.py:1463-1490). The map is built once at import (server_capabilities(), app.py:1378-1462), so a Chromium or ffmpeg installed later shows up only after a service restart. A flag that is absent or false means the feature is not there.

3. Terminal-side conventions

Nothing in this section is an API call: it is how the agent's printed output behaves on the user's device. Printing something never opens it; the user taps it.

3.1 Local paths (08-links.js:13, trimPath :225)

LOCAL_PATH_RE = /(?:^|[\s"'`(\[{<=:,])((?:~\/|\/)[^\s"'`()\[\]{}<>:;,]+)/g

• The path must start with / or ~/, at the start of a line or right after whitespace, a quote, a backtick, (, [, {, <, =, : or ,. A bare logo.png or a relative src/app.py is not a link.
• The path ends at whitespace, a quote, a backtick, any bracket, <, >, :, ; or ,. So app.py:42 links only app.py, and a path containing spaces is cut at the first space. Trailing . ! ? ' " $ % # are trimmed, and a bare / is dropped.
• Wrapped paths are rejoined across up to 8 rows, including continuation rows indented by up to 4 spaces (logicalLine, stitchedText).
• A https?:// URL on the same row takes precedence over any path inside it.

What a tap opens (activateLink 08-links.js:240, openEntry 28-file-explorer.js:1840-1866):

A path that does not exist gets a "Couldn't find" toast. Media and PDF paths are not previewed at a git ref.

3.2 URLs, http://localhost:PORT and the relay (08-links.js:18, :320-408)

• URL_RE = /https?:\/\/[^\s"'`<>]+/gi; trailing . , ; : ! ? ' " and unbalanced closing brackets are trimmed.
• Laptop (wide layout) with the browse capability: every http(s) URL opens in the in-app browser pane, fetched by the computer, so http://localhost:PORT works there directly with no relay.
• Phone (or a laptop without browse): the URL opens in a new browser tab. If the host is localhost, 127.0.0.1, [::1], ::1 or 0.0.0.0, the phone first rewrites it to the computer's address as the phone knows it, then fires POST /api/relay {host, port} without waiting. The backend binds that port number on that address and forwards it to the loopback listener. It answers relayed, direct (something already listens there) or refuses (not_listening if nothing is on loopback at that port, bad_host for a loopback or wildcard target).
• What the agent should do: print http://localhost:<port> after the server is actually listening. It needs no API call. The relay binds on tap, not on print, and a server bound to 0.0.0.0 is reachable as printed.

3.3 Pane title and cwd

• Session row label: set the pane title with OSC 2 (or OSC 0): printf '\033]2;%s\033\\' 'Running tests'. The list strips leading non-alphanumeric glyphs and shows the rest. A title of the form user@host: /path, or equal to the hostname, is ignored and the folder name is shown instead (06-session-list.js:250-263, app.py:711-716).
• Explorer "open at this pane's folder" and docked-pane follow: for a local pane this is tmux pane_current_path, the cwd of the pane's foreground process (pane_cwd, app.py:786-829). A cd typed at the shell moves it; a cd inside an agent's own tool subprocess does not. To point the user at a folder, print its absolute path.
• ssh panes only: when the pane's foreground command is ssh, the title is read as user@host: /abs/path (everything after the first colon; ~ paths refused). A global tmux hook (pane-title-changed, TITLE_HOOK, app.py:741-775) copies every title that matches *@*: /* in an ssh pane into the pane option @ptui_remote_cwd, so a TUI that later overwrites the title does not erase it. The path is used only if it exists on this machine, directly or through POCKETTUI_PATH_REWRITES. For this to work, the remote shell must have drawn such a title in that folder before the TUI started.

3.4 How "waiting", "ready" and "idle" are derived (app.py:10170-10780)

The watcher polls every 2 s. A session is active while its newest output is less than 6 s old (POCKETTUI_NOTIFY_IDLE_S). At the busy-to-idle edge it reads the visible pane once, if the busy episode lasted 10 s or more or a non-shell program still holds the pane. detect_prompt then checks the last 5 non-empty lines above an empty composer, in this order:

1. [y/n], (y/n) or yes/no → waiting, chips y n.
2. Two or more adjacent lines matching ^\s*│?\s*(❯\s*)?\d+[.)]\s (numbered menu, box border tolerated) → waiting, chips are the first four digits.
3. Exactly one line ❯ <text> with a non-empty line under it (unnumbered chooser) → waiting, no answer chips.
4. do you want | would you like | proceed? | continue? | are you sure → waiting, chips y n.
5. The cursor line is a composer (> or ❯, optionally after │) that is empty, or holds only dim (SGR 2) placeholder text → ready. Non-dim text in it → drafting, shown as idle and never notified.
6. The cursor line ends in ? → waiting, no answer chips.
7. Otherwise → idle.

Chips always add Enter (\r) and Esc. A chip tap sends only that key, with no Enter after y or a digit, and the chips come down as soon as the pane prints again.

Notifications (Web Push and/or ntfy) go out only for sessions whose @notify is on or quiet. At most one goes out per 30 s per session, and a repeat of the same text is suppressed:

• waiting: at once;
• ready: only after 30 s or more of work (POCKETTUI_NOTIFY_READY_BUSY_S);
• "<cmd> finished": a run of 10 s or more that returned to a shell;
• "went quiet — may need input": a program went silent after 10 s or more of work;
• terminal bell: printf '\a' notifies immediately, with no text guard, provided tmux sets the window's bell flag (tmux may not flag a bell in a window a client is currently viewing).

For an agent to be detected correctly:

• Ask with a literal (y/n) or a numbered list (1. …, 2. …), then stop printing. Spinners, clocks or status lines that repaint keep the session active and defer detection.
• Keep the question within the last 5 non-empty lines above the input line.
• When done, return to an empty prompt/composer; a plain shell prompt after a long command reads as finished.
• Keystrokes the user sends from a phone reset the repeat guard; typing at the physical keyboard does not.
• There is no route that marks a session waiting or sends a push. POST /api/notify only stores the per-session preference.

3.5 Files that arrive from the user

• Pasted image: ~/.pockettui/images/paste-<stamp>-<hex>.<ext>. The type is sniffed from the bytes and the newest 30 are kept (app.py:8660-8735). The absolute path is typed at the user's cursor.
• Attached file: ~/.pockettui/uploads/<name>-<stamp>-<hex>.<ext>, newest 30 kept (app.py:8766-8837).
• Browser-pane upload for a streamed page: ~/.pockettui/uploads/browser/<hex>/ (app.py:8126). Streamed downloads: ~/.pockettui/downloads.

4. Documented HTTP routes an agent may use

All need X-PocketTUI-Token except /.well-known/pockettui. None of them changes what is on the user's screen.

GET  /.well-known/pockettui   (no token)                    -> {product:"pockettui", version}
GET  /api/version             -                             -> {version, host, capabilities:{<flag>: bool}}
GET  /api/sessions            -                             -> {sessions:[{name, created, attached, windows, command, title, cwd, alias, notify, state: active|waiting|ready|idle, last_activity}]}
POST /api/session             {name, dir?}                  -> {session} | 400 {error} (name required, <=60 chars, no "." or ":", unique; dir defaults to ~)
POST /api/alias               {session, alias}              -> {session, alias}   (display name only; "" clears)
POST /api/session/rename      {session, name}               -> {session}           (real tmux rename; drops every device view)
POST /api/session/type        {name, dev?, text}            -> {session, chars} | 400 empty | 404 | 413 too_long (>4096)  (typed with send-keys -l, \r and \n stripped, never submitted)
POST /api/notify              {session, mode: off|on|quiet} -> {session, notify}  (preference only; sends nothing)
POST /api/session/kill        {session}                     -> {killed}           (whole group; only on explicit user request)
GET  /api/update_status       -                             -> {state: <install.sh update-state.json> | null, session_alive: bool}

Prefer the CLI where one exists: pockettui update | version | status | browser install|check|status. Prefer plain tmux for reading your own pane.

POST /api/alias  {session, alias}  -> {session, alias}

POST /api/session/kill  {session}  -> {killed}

GET /api/sessions  -  -> {sessions:[{name,created,attached,windows,command,title,cwd,alias,notify,state,last_activity}]}

POST /api/session  {name, dir?}  -> {session}

POST /api/session/type  {name, dev?, text}  -> {session, chars}

POST /api/notify  {session, mode: off|on|quiet}  -> {session, notify}

GET /.well-known/pockettui  (no token)  -> {product:"pockettui", version}

GET /api/version  -  -> {version, host, capabilities:{<flag>: bool}}