Mobile Guide
Codeman on a phone is not a shrunken desktop UI. It is the surface most of its design attention has gone into, because checking on an agent from a bus is the thing this software is for.
- Set up access. Tailscale is the recommended route and gives you real HTTPS. See Remote Access.
- Log in by QR. Open the dashboard on your desktop and scan the code. No password typing. Tokens are single use and rotate every 60 seconds.
- Install it to your home screen. On iOS this is mandatory for push notifications; Safari does not deliver push to tabs. On Android it makes the app full screen.
HTTPS matters for more than security here: microphone access and push notifications both require a secure context.
| Element | Where |
|---|---|
| Header | Fixed at the top, deliberately minimal. Desktop-only controls never appear. |
| Tab strip | Scrolls horizontally. The active tab is always scrolled into view. |
| Terminal | The rest of the screen. |
| Toolbar | Bottom: Run, Stop, Enter, case picker, voice, settings. |
| Keyboard bar | Above the on-screen keyboard when it is open. |
Layout respects notch and home-indicator safe areas, touch targets are 44px, and the case picker is a bottom sheet rather than a dropdown.
Swipe left and right on the terminal to switch sessions.
Tapping the "C" logo gives a session overview rather than a welcome page:
- NEEDS YOU first: sessions blocked on a question, with answer strips so you can resolve them without opening the session.
- CURRENT SESSIONS with live status.
- PAST SESSIONS, resumable.
Row status uses the same language as the tabs: green when fine, pulsing while working, yellow when waiting for input, red when a question is pending.
The split Run button carries the same per-backend colours as the desktop toolbar, and its picker mirrors the desktop run-mode menu.
On by default; it can be turned off in settings.
A row of keys above the virtual keyboard, and what it contains depends on the session.
Agent sessions get quick actions: /init, /clear, /compact, a clipboard key, Esc,
a path picker, an image key, and 🧠 when Read My Mind is on. Destructive commands need a
double press, so you cannot fire /clear with a stray thumb.
Shell sessions automatically swap it for terminal controls: Ctrl, Esc, Tab, four
arrows, paste, and dismiss. Your normal preference is remembered and restored when you
switch back to an agent session, so a settings change during a shell session cannot strip
the bar away permanently.
Ctrl on the shell bar is a one-shot modifier: tap Ctrl, then tap c, and the
control byte is sent. It disarms on use, on a second tap, on any other accessory key, on a
session switch, and when the keyboard closes.
That list matters. A modifier left armed turns your next innocent keystroke into a control byte, so it is deliberately eager to disarm. Keys with no control equivalent pass through unchanged, exactly like a hardware keyboard.
The toolbar's dedicated Enter button exists because of local echo. On a phone, the characters you type are painted locally and have not reached the agent yet; Enter flushes them and then submits.
It replays the keypress through the terminal rather than sending a bare carriage return.
Sending a bare \r would submit an empty line and strand your typed text on screen, which
looks exactly like a dead button.
On phones this button replaces the desktop's Run Shell control; starting a shell moved into the Run dropdown.
- Tap a link in terminal output and it opens in a new tab. Same for a link in an agent's answer in the response viewer — it opens a tab rather than navigating the dashboard away, which on a phone would unload the whole session view.
- Tap a file path an agent printed and the file-preview overlay opens; a log path opens the log viewer. Works in scrolled-up transcript too.
- A tap on the prose beside a link still places the cursor as usual, and a tap on a dialog's numbered choice still answers the dialog even when the row contains a path — the dialog wins, because on a phone it is the only interaction that matters.
- Long-press to select text, then drag, or tap the other end to extend the selection — no hairline handles to grab. A small bar offers Copy, Line (the whole logical line, wrapped rows included) and dismiss. Copy works on plain-HTTP installs too, where the browser clipboard API is unavailable.
- A swipe is never mistaken for a long-press, and the keyboard stays down while you select.
- The terminal and toolbar shift up when the keyboard opens, tracked through the browser's visual viewport rather than guessed.
- Two ways to dismiss the keyboard: tap outside the terminal on inert space, or tap twice on inert terminal content. Tapping a control never dismisses it, and tapping the prompt row keeps focus so you can place the caret.
- A scroll is never mistaken for a tap: travel is measured from the start of the gesture, and multi-touch never counts.
- A long prompt stays visible. Once what you are typing wraps past the last visible row it grows upward over the transcript instead of sliding under the keyboard, so the end of the sentence — where the cursor is — is always on screen. A prompt taller than the visible strip shows its tail.
The microphone button, or the keyboard bar. Providers and setup are covered in Input And Voice. Dictating is often faster than typing a prompt on a phone, and it is the main reason the feature exists.
Push notifications reach you with no tab open, and with the Approvals Inbox on they carry Approve and Deny buttons handled by the service worker, so you can unblock an agent from the lock screen.
Setup in Notifications And Approvals.
The terminal viewport is small. Last Response (opt-in header button) renders the agent's last answer as scrollable text instead, with a More button for additional context.
The File Viewer works on phones too, including edit mode, which is enough to fix a typo an agent introduced while you are away from your desk.
- Extra header buttons. New header controls are kept off phones by policy, with a test that enforces it.
- The Approvals bell. Phones get the NEEDS YOU strips on the home screen instead.
- The desktop home tab rail, which needs a wide window.
- Lineage arcs, which are a desktop overlay.
- Typed text sitting on screen has not been sent. Press Enter.
- iOS needs the home screen install for push, not just a bookmark.
- iOS Safari can serve stale JavaScript after an update until the tab is fully closed. Close it and reopen.
- Plain HTTP over a LAN address disables voice and push. Use HTTPS.
-
An armed
Ctrlis visibly highlighted. If it looks the same as a resting key, you are on an old version, on a light skin.
- Remote Access - getting the phone connected in the first place.
- Notifications And Approvals - being told when you are needed.
- Input And Voice - local echo, dictation, and the input rules.