Mobile app

Pragma Go is the mobile client (iOS, iPadOS, Android, and the web). It talks to the same host as the desktop through the gateway — a localhost HTTP server the desktop starts — exposed over a tunnel you configure.

Installing Pragma Go

• iOS — download Pragma Go on the App Store.
• Android — install the APK with Obtainium, below.
• Web — nothing to install; see Pragma Go on the web.

Android with Obtainium

Pragma Go for Android is not on the Play Store. Every pragma-go release on GitHub carries a signed APK instead, and Obtainium installs it straight from there and notifies you when a new one ships.

1. Install Obtainium from its releases page or F-Droid. Android asks you to allow installs from that source the first time.

2. In Obtainium, tap Add app and enter the source URL:

   https://github.com/pragma-sh/pragma

3. Set the additional options. The same repository publishes the desktop app and every agent plugin, so Obtainium needs to be told which releases are Pragma Go's:

   Option	Value
   Filter release titles by regular expression	^pragma-go
   Filter APKs by regular expression	\.apk$
   Fallback to older releases	On
   Version detection	Use release date as version string

4. Tap Add, then Install, and accept Android's install prompt.

5. Open Pragma Go and pair it with your desktop.

Updates arrive the same way: Obtainium checks in the background, notifies you, and installs the new APK over the old one with your data intact.

Pairing a device

Settings → Pragma Go:

1. Turn on Remote access. Pragma starts the tunnel and shows a QR code.
2. Scan it with Pragma Go. The payload contains the tunnel URL, the gateway token, and the gateway API version, which the app checks before it stores the connection.

Prefer manual? Expand Manual for copyable URL and Token rows.

Pragma Go remembers the desktops it has connected to. They appear under Previous connections on the pairing screen: tap one to reconnect with its saved token, or Remove it. In the browser, connections are kept in session storage unless you choose Remember this browser, so closing the tab clears them. Settings → Unpair this device returns to the pairing screen straight away, even if the desktop is unreachable. The app tells the desktop to stop sending notifications in the background and tries again on the next launch if it gets no answer. Regenerating the token on the desktop invalidates saved connections too. Scan the QR code again after doing that.

Keep awake (on by default) stops the computer from sleeping while remote access is on, so sleep will not interrupt pairing. On Linux it also blocks sleep on lid close; macOS and Windows still sleep when the lid closes unless an external display keeps them awake. Turn it off to let the machine sleep normally (gateway.keepAwake in ~/.pragma/config.json).

The tunnel command lives in ~/.pragma/config.json under tunnel; the default uses ngrok http {port}. Any command that prints a URL works — urlPattern tells Pragma how to read it back. Regenerate token invalidates every paired device.

Pragma Go on the web

Enable web access serves the Pragma Go web build from the same gateway. When the tunnel is active you get a Web app link — it carries the token in the URL fragment (#), which browsers never send to a server, so the link can be pasted into a browser on any machine. The warning is real: the link contains the token, treat it like a password.

What you can do from the phone

• Create worktrees and launch agents — sessions appear on the desktop as background tabs.
• Watch running sessions and read scrollback. Swiping a terminal only scrolls it — it never sends keystrokes or mouse input to the program running there.
• Open terminals and type into them — see Terminals.
• Run project scripts and open the ports they listen on — see Project scripts and ports.
• Commit and open the pull request — see Commit & PR.
• See every agent account's usage and switch accounts — see Accounts.
• Answer questions and approve commands — the same prompts the desktop shows, answered from wherever you are.
• Read and comment on scratchpads, including embedded whiteboards, which the host renders for the phone.
• Your custom agents and their icons resolve exactly as they do on the desktop.
• Fan out one prompt to several agents and compare the attempts — see below.
• Browse a worktree's files and read any of them, or an attempt's changes, read-only.

Fanouts on the phone

In the launch sheet, Run in → Fan out turns the agent picker into attempt rows: one agent, model, and effort per attempt (at least two, the same model twice is fine). Name the fanout's branch, write the prompt every attempt runs, and tap Fan out. Like the desktop, the attempts hang off a fresh coordination branch made from the worktree you opened the sheet on — see Fan out.

Attempt worktrees are folded into a single fanout row under their parent, with a combined status dot. Tapping it opens the compare view: the attempt in view heads the screen — its agent and status — with a chip row under it to jump to another, and one page per attempt, swiped between. Each page shows the scratchpads the attempt wrote and every file it changed against the fanout's base commit — tap a file for its diff. Screens you open from here go Back to the fanout. The header's buttons act on the attempt in view:

• Chat (speech bubbles) goes to the attempt's live session.
• Retry (circular arrow) restarts an attempt's agent in its existing worktree, keeping its work.
• Pick (check) commits and merges it into the fanout branch, then deletes every attempt worktree — the phone asks first. A merge conflict is left for the desktop to resolve.
• The composer at the bottom sends a follow-up to all attempts or only the one in view.
• ⋯ → Cancel fanout stops every attempt and keeps their worktrees.

Files

The bottom of a worktree's screen is a file explorer, like the desktop's Files tab: folders expand in place, and tapping a file opens it in a read-only viewer with the desktop's syntax highlighting. Wrap / No wrap in the header toggles soft wrapping. Binary files and files too large for the host to send say so instead of rendering. Nothing on the phone can edit, rename, or delete a file.

Terminals

A worktree's Terminals section lists its shells and script runs; agent sessions stay under Agents, where the chat screen's Chat / Terminal switcher reaches the agent's raw TUI. Tap a row to attach to it, or New terminal to open a fresh shell. A terminal opened from the phone is a real tab: it shows up on the desktop too and outlives the desktop window. It is still an ordinary shell, so a host-server restart ends it and it reopens fresh — see Sessions & recovery.

• The keys a phone keyboard lacks sit above it: ctrl (sticky), esc, tab, ^C, and the arrows, with the rest one tap away under ⋯. Ctrl-D is deliberately not next to Ctrl-C — it ends the shell.
• While you look, the phone borrows the terminal's size; leaving hands it back, so the desktop's layout is untouched. If the phone stops answering, the host takes the size back on its own.
• A dropped connection resumes from where it left off rather than replaying the whole scrollback, and a keystroke whose delivery was uncertain is never resent.
• Long-press a row to Rename it or Close terminal. Closing ends the process on every device, so the phone asks first. Renaming needs Pragma open on the computer.

Project scripts and ports

The worktree header's play button lists the project's run scripts. Tapping one starts it on the host without leaving the screen; its terminals appear under Terminals, one per command. A script that is already running shows as Stop <name> instead, and tapping it again never starts a second copy fighting for the same port.

While a worktree is open, a Ports section lists the servers its terminals are listening on, with the process that owns each. Tap one and confirm Forward port …?: Pragma exposes it through your configured tunnel command and opens it in the phone's browser. Forwarded pages carry a draggable paintbrush — tap it to pick elements, describe a change, choose an agent, and launch it, the same flow as the desktop browser's design mode. The paired gateway token never enters the forwarded page.

Commit & PR

The worktree header's pull-request button runs the desktop's Commit and draft a PR flow, in the same order: AI groups your changes into logical commits, you review and edit the pull request Title and Description and choose the branch to Merge into, and only then does Push & create PR push and open it (Open as draft first if you like).

The run belongs to the host, not the phone: locking the screen or losing signal neither cancels it nor starts it twice, and the sheet shows the host's stage — Reading your changes…, Committing…, Writing the pull request…. A run that fails, is stopped, or is interrupted says how many commits it already made. The button is disabled when the worktree has nothing to commit, and asks you to Sign in to GitHub first when the host has no GitHub token — see GitHub.

A worktree whose branch has a pull request shows it at the top — including one opened on the web or from another machine — and says merged rather than closed once it is merged.

Accounts

The home screen lists every account provider: each account's plan usage, with a reset countdown, and which account each agent launches with. Switching here changes the all-projects choice; a project override set on the desktop still wins inside that project, and running agents keep the account they started with. Signing in to a new account is done from the desktop.

Widgets

On iOS, long-press the Home Screen to add Pragma Go widgets:

Widgets cannot reach your computer themselves; they show the state from the last time the app ran, and tapping a row deep-links into it.

Notifications

Agent status drives push notifications to paired devices, using the same wording and sound choices as the desktop. If the desktop is focused, pushes are suppressed — one device needs the answer, not both.