[tebiggs]

Claude Code can now run on an Android phone itself, as a normal T3 Code provider. T3 Code clients never run providers, so the phone runs its own T3 server inside Termux and the app connects to it over 127.0.0.1 like any other environment. "No project" threads, local-folder projects and folder browsing then work on the phone unchanged.

How it works

• Add environment → Run agents on this phone (Android, 64-bit) opens a checklist. Every step is detected again whenever the screen gains focus or the app comes back from Termux, so the user can leave for Termux and the app can be killed without losing track:
  1. Install Termux (F-Droid).
  2. Let T3 Code use Termux: the RUN_COMMAND runtime permission, plus one pasted command that sets allow-external-apps = true (only Termux can set it). Permanently denied, Termux refusing, and Termux not answering each get their own message.
  3. Install Ubuntu, Claude Code and T3 Code. Termux opens and runs the installer, which takes a lock, records progress (the app shows "step N of 4", "stopped at step N" or "Finish install"), and only adds what is missing. A hand-made Ubuntu with Claude Code already signed in is kept as it is.
  4. Sign in to Claude: Termux opens claude auth login. Fallback: t3-phone shell, then claude auth login. Sign out is the reverse.
  5. Connect: starts t3 serve --host 127.0.0.1 as a Termux background task (output in ~/.t3-phone/server.log), mints a token with t3 pair inside Ubuntu, and pairs with expectedEnvironmentId set to whatever answered on the port, so a different listener can't be added by mistake.
• Keep it running shows Termux's battery exemption and phone storage access, and links to the developer option that turns off Android's child-process limit (plus Samsung's "Never sleeping apps").
• Afterwards: the app starts the server when it opens (at most once a minute, foreground only, off after an explicit Stop). Home shows a chip while it's down (tap to start, or open setup if starting failed). The environment page has Setup, Start/Stop and the auto-start switch. Removing the environment offers "Remove and stop server". Add project → Local folder gets Phone storage / Downloads / Documents / Ubuntu home shortcuts.

Pieces

• apps/mobile/modules/t3-termux/: Expo module that sends Termux's RUN_COMMAND intent. Short background runs return stdout and the exit code through a PendingIntent; the server runs as a background task with no result; interactive steps get a terminal session, and the app brings Termux forward itself because Termux can't from the background on Android 10+. assets/t3-phone.sh is the one script behind every step (status, install, serve, stop, pair, login, logout, storage); it ships with the app, so it updates with the app, and install also saves it as t3-phone in Termux.
• apps/mobile/src/features/phone/: checklist screen, step logic, server start/pair/auto-start, Home chip, environment section, folder shortcuts.
• The server runs as proot's fake root with IS_SANDBOX=1, because Claude Code refuses full access as root otherwise. A separate Ubuntu user would add no isolation (it all runs as Termux's uid) and would make people who set Claude up by hand sign in again.
• Fork releases now also build the Linux arm64 server (fork-release.yml, on GitHub's ubuntu-24.04-arm runner, like upstream's arm64 job). The phone installs the fork's newest release that has a server for its CPU, and falls back to upstream's nightly until one exists. A plain t3 serve can't update itself, so the phone's environment page has Update T3 Code: it installs the newest build and restarts the server.

No server changes. iOS is unchanged.

Testing

• t3-phone-script.test.ts runs the real script under bash against a fake Termux (stubbed pkg, proot-distro, am, guest claude/t3): fresh status, a hand-made setup with Claude signed in, signed out, fresh install order and self-save, skipping finished parts, the install lock, a failed Ubuntu step, and pair parsing.
• phone-setup.test.ts covers step order, the Termux opt-in states, token expiry, and install states (partial, running, killed midway, old failure).
• t3-phone-script.test.ts also covers serve (supervises, logs, gives back its locks; no second server) and stop (a reused pid is left alone; success only once the supervisor is gone; failure keeps the lock), plus status during a running install, and update (picks the fork's newest server for the CPU from pretty or compact API JSON, falls back to upstream only when the fork has none, keeps the installed server when GitHub can't be reached, one update at a time).
• Typecheck, lint, knip, ktlint and detekt pass.
• Not yet run on a phone. Untested on hardware: the RUN_COMMAND result delivery, proot-distro 4.x vs 5.x on a real device, termux-open-url from inside Ubuntu, and t3 self-update under proot (a plain t3 serve offers no in-app update).

Mocks and a UX review (Claude Fable 5.1) shaped the flow before implementation: one detected checklist, and a failure state for every step. Six adversarial review rounds by GPT-6.1 Sol (Codex) followed; the later commits fix what they found, mostly around the server's lifecycle: a background terminal session that never started its process, Termux not coming forward on Android 14+, stop safety and confirmation, lock races, wake-lock cleanup, and the server updater.

Built with Claude Opus 5.5 in Claude Code (T3 Code).

🤖 Generated with Claude Code