feat(android): native phone app for Remote Access

[BigWebstas]

Description

Adds a native Android app (android/, Kotlin/Compose) for Remote Access, plus the desktop routes it relies on. This replaces #292 and adds everything built since then.

Android app

• Connecting:
  • Connect by QR code or link and pair with the desktop PIN.
  • Link several computers, each with its own pairing, and switch between them quickly.
  • Optionally wait for a VPN before connecting, and skip that wait on the home Wi-Fi.
• Agent list: minimized tasks, pull to refresh, and a home-screen widget that totals agents across computers. Usage meters, including Claude credit usage, appear when the desktop serves /api/mobile/usage (added in feat(git): commit dialog, plus phone commit and usage routes #298); otherwise they stay hidden.
• Terminal:
  • Uses the desktop's colors and look presets, wraps long lines, and follows reliably (optionally always jumping to the latest output).
  • Has quick keys, quick replies and voice input.
  • An opt-in mode sizes the PTY to the phone.
• Task actions: per-file diffs, notes, new tasks, and merging with readiness checks. Closing a task shows the same warnings as the desktop's Close Task dialog.
• Built-in chat tasks: transcript, approvals and questions, send and stop.
• Notifications: optional alerts when an agent needs input, errors or finishes. This runs as a foreground service and is off by default.
• Backup: back up and restore the phone's data.
• Look and feel: Obsidian dark and light themes, splash screen, themed icon, predictive back, animations and haptics.
• Release builds: shrunk with R8 to about 2 MB. A CI workflow (.github/workflows/android.yml) builds, tests and releases the app.

Desktop support

• New routes:
  • GET /api/mobile/tasks/:id/diff, POST /api/mobile/tasks/:id/close, GET /api/mobile/tasks/:id/readiness and POST /api/mobile/tasks/:id/merge.
  • All are renderer-backed like notes. Reading works with a view-only token; changes need pairing.
  • Without force, close and merge answer 409 with their warnings instead of acting.
• Phone web UI: gets the same diff review and task actions.
• view-size WebSocket message: a paired phone may size a terminal while viewing it.
  • The desktop pane's size is remembered and restored on release or disconnect.
  • Only the phone that set the size can hand it back.
• Terminal history:
  • Subscribing sends a rendered snapshot of the screen plus the full scrollback, taken from the existing main-process headless mirror (@xterm/addon-serialize).
  • This replaces the raw byte replay, which agents that redraw often fill with repaints of a single screen.
  • Exited agents still get the raw replay.
• Minimized tasks appear in the phone's agent list.

Overlap with my other PRs

• This branch also contains the Claude credit-usage change from fix(usage): show Claude credit usage when a login has no rate-limit windows #295, because the phone shows the same data.
• The phone's Commit / Stage all / Unstage all button calls /api/mobile/tasks/:id/commit, which is added in feat(git): commit dialog, plus phone commit and usage routes #298. Without that route, the button reports an error and the rest of the app is unaffected.

Build and install instructions are in android/README.md.

Screenshots

Agent list (Ember)	Agent list (light)	Terminal	Terminal (Noir)

Changes	Commit	Looks	Home-screen widget

Issues Resolved

None directly. Related to #192 (installing on Android): this offers a native app instead of the PWA.

Check List

• New functionality includes testing.
• New functionality has been documented in the README if applicable. (The app has its own android/README.md.)

🤖 Generated with Claude Code

[johannesjo]

🔧 Needs changes – labelled needs work; ping me once the items below are addressed and I'll re-review.

Thanks for the PR! This adds a native Android client for Remote Access plus the desktop endpoints it needs (task actions, view sizing, rendered snapshots). The desktop side is solid overall, but a few things need fixing, and the branch currently conflicts with main.

Should fix before merge

• src/remote/api.ts:163 – on a 409 closeTask returns { warnings: [err.message] }, but request() only keeps j.error, so the server's warnings array (uncommitted changes, unmerged commits, coordinator children) is dropped. The web dialog then shows only "closing would lose work", and "Close anyway and discard the work listed above" has nothing listed. The Android client reads warnings correctly; the AgentDetail tests mock closeTask, which hides this. Fix: keep the parsed body on ApiError (or call fetch directly here) and return body.warnings, with an api-level test.
• src/remote/TaskActionsDialog.tsx:243 – "Unmerged work on its branch stays on the branch." is not true by default: the store's closeTask deletes the branch when the project's deleteBranchOnClose is set, and that defaults to true. Combined with the item above, the phone hides the "unmerged commits" warning and promises the work survives. Fix: drop the sentence, or word it from the project setting the way the desktop CloseTaskDialog does.
• electron/remote/server.ts:2126 / :2221 – view-size ownership is released only by an explicit view-size null or the ws close event, and the server has no heartbeat. A phone that drops off Wi-Fi without a close frame keeps owning the PTY size, and since resizeAgent only records the desktop size while a remote size is set, the desktop pane stays at phone width: indefinitely for an idle agent, otherwise until a TCP write times out (roughly 15 minutes). Fix: a server-side ws ping/terminate() heartbeat, or let a desktop resize reclaim the size.
• .github/workflows/android.yml:9 / :11 – the paths filters cover only android/** and the workflow file, but LookPresetsGeneratedTest checks the generated looks against src/styles.css, src/lib/look.ts and src/lib/theme.ts. A desktop-only theme change passes CI and the next Android PR breaks instead. Fix: add those paths and scripts/generate-android-looks.mjs to the filters, or run npm run check:android-looks in ci.yml.
• Rebase – the branch conflicts with main (electron/remote/server.ts, electron/ipc/register.ts, src/store/remoteTaskHandler.ts, the channel manifest and electron/preload.cjs). After rebasing, handleGetMergeReadiness should pass evidence to buildMergeReadiness the way merge-state.ts now does.

Nits

• .github/workflows/android.yml:7 – branches: [main, feat/android-phone-app] names your fork branch; branches: [main] is enough upstream.

Questions

• electron/remote/ring-buffer.ts:7 – the default capacity goes from 64 KB to 2 MB, allocated up front for every PTY, and the PR description doesn't mention it. Now that live agents get rendered snapshots, what still needs the larger raw buffer? If it's only for the phone's history, could it stay small by default and grow only for agents with a remote subscriber?

---

_{Automated review pass (Claude Code). Anything unclear or wrong – say so and I'll take a look. I read the desktop changes in full and the Android client selectively (networking, manifest, backup, build config); I didn't run anything.}

[johannesjo]

Thanks a lot for this, @BigWebstas! I'd like to take the Android app in. I've started working through the review items above on top of your commits (rebase onto main, the close-dialog warnings, the view-size heartbeat, the CI path filters), so please hold off on rebasing for now to avoid duplicate work. I'll follow up here.

[johannesjo]

Thank you very much for this! <3