English · 简体中文
Stop using your phone as a tiny remote for a distant server.
Put a real Linux + official Pi Coding Agent workstation straight in your pocket.
Native Jetpack Compose · Official Pi 1.6.0 SDK · Bilingual EN / 中文 · Three Linux Runtimes · Full Extension & TUI Parity · Zero Root, Zero Termux
⬇ Download Latest APK · Build Status · Issues & Ideas
When you're away from your desk and want an agent to actually get work done, you usually face three frustrating compromises:
- Chat-box wrappers: fine for copy-pasting snippets, useless for reading a real repository, running
git diff, executing tests, or loading MCP servers and extensions. - SSH into a remote box: breaks on spotty transit networks and turns reading diffs into squinting at microscopic scrolling terminal text.
- Hand-rolled Termux setups: hours of bootstrapping packages, wrestling with permissions, and fighting tiny virtual keyboards before you write a single line of code.
Pi for Android throws all three compromises away.
It bundles a complete Ubuntu 24.04 ARM64 userspace + Node.js 24.22.1 + Git + ripgrep + fd + the official Pi Coding Agent 1.6.0 SDK inside a single native Jetpack Compose APK. No root. No Termux. No cloud sandbox. Zero setup scripts. Install the APK, open any real folder on your phone, and start working with a real local coding agent.
| Capability | Typical AI Chat Apps | Termux / SSH | Pi for Android |
|---|---|---|---|
| Real local Linux + Node + Git + rg + fd | ❌ Chat only | ✅ Built-in, zero root, zero Termux | |
| Mobile-native diffs & reading stream | ❌ Tiny scrolling TTY | ✅ Tonal tool cards, intra-line diffs, LaTeX, Mermaid | |
| Desktop Pi extensions & interactive TUI | ❌ Unsupported | ✅ Virtual TUI surface projection + touch/mouse + auto-fit | |
| Full Pi model, MCP & Code Mode ecosystem | ❌ Closed / limited | ✅ CLI only | ✅ Real Pi 1.6.0 SDK · 7 OAuth logins + 35+ providers |
| Opt-in Android device automation | ❌ Impossible | ✅ Zero-token device bridge + native confirmation gate |
Most mobile agent clients hit "desktop terminal extensions & custom TUIs" and give up. Pi for Android built a real virtual TUI projection & official renderer pipeline so upstream Pi extensions feel right at home on a touchscreen:
- Virtual TUI Surface Projection (
ui/surfaces.mjs→ Jetpack Compose):- Extensions calling
ctx.ui.custom(),setWidget(),setHeader(),setFooter(), ortui.showOverlay()mount real Pi TUI components into an in-host virtual surface — minimizable to a dock, collapsible, and reopenable at any time. - Full
OverlayHandle(hide/setHidden/focus/unfocus/getBounds),Focusable.focused, andOverlayOptions(visible(w, h),nonCapturingfloating HUD overlays, anchors) parity. - Responsive 80-col width-fitting + touch & keyboard dispatch: scales 80-column desktop TUI layouts cleanly into your phone viewport, reports real columns back via
ui.resize, wires officialKeybindingsManager, renders clickable OSC 8 hyperlinks, and translates touchscreen taps intoTuiMouseEventforhandleMouse(). - Terminal control sequence bridge: strips zero-width
CURSOR_MARKER, turnsFAKE_CURSORinto inverse SGR, and interceptsBEL(\x07) sound bells,OSC 777 / 99 / 9notifications,OSC 0/2window titles, andOSC 9;4progress indicators — even interactive TUI games with terminal bells come alive on Android.
- Extensions calling
- 1:1 Official Extension Renderers & Hooks (
commands/catalog.mjs):- Extension & MCP tool cards run through Pi's own
ToolExecutionComponent(resolveToolRenderers), preserving per-callstate,details,renderShell: "self", debouncedrender.invalidate, and clean cache invalidation on/reload. - Complete plumbing for
registerMessageRenderer(CustomMessageComponent),registerEntryRenderer(CustomEntryComponent),registerMarkdownTransformer,addAutocompleteProvider,onTerminalInput,registerShortcut(catalog.shortcuts/triggerShortcut),ctx.ui.getAllThemes()/getTheme()/setTheme(),registerFlag,FooterDataProvider(live git branch & provider count), plus officialresetExtensionUIand 1-tap reload (catalog.changed).
- Extension & MCP tool cards run through Pi's own
- Bundled Native-Enhancement Extensions (
app/src/main/assets/pi-extensions/):pi-highlight: exposes Pi's own guesthighlight.js+lovely-mermaidover an authenticated local loopback service — instant syntax highlighting and Mermaid rendering with zero second JS runtime on Android and 100% official theme parity.pi-android-bridge&pi-android-permission-gate: bridges opt-in Android device automation into Pi as a standard extension — 0 tokens when off, native 3-choice confirmation dialogs for irreversible actions.
- Unified Transparent Resource, Tools & Prompt Control:
- Settings → Extensions & Resources: extensions, skills, prompt templates, themes, context files, npm/git packages, MCP servers, and project trust in one place — with quick delete for user-owned files and 100% desktop
~/.pi/agent/&.pi/compatibility. - Settings → Tools: live switches for every built-in, built-in extension (
codemode,mcp), and user extension/MCP tool, with Save as Default (defaultTools), Pi 1.6.0 Codemode settings, and officialshellCommandPrefix. - Unified System Prompt & Context + In-Chat Inspector: edit global & project
APPEND_SYSTEM.md,SYSTEM.md, andAGENTS.md/CLAUDE.mdwith 1-tap reload, or inspect the active assembled prompt with XML section filters directly from the chat top-right command center.
- Settings → Extensions & Resources: extensions, skills, prompt templates, themes, context files, npm/git packages, MCP servers, and project trust in one place — with quick delete for user-owned files and 100% desktop
First launch unpacks a deterministic, per-payload versioned Linux environment (Ubuntu 24.04 ARM64 · Node.js 24.22.1 · Git 2.43 · ripgrep 15.2 · fd 10.2 · Pi 1.6.0). Future APK upgrades diff per-payload digests and only refresh what changed, keeping packages and tools you installed inside the guest intact.
| Runtime | Role |
|---|---|
| PRoot | Battle-tested user-space syscall translation (Termux build) — the compatibility baseline. |
| Proroot | Linker + in-process hook runtime built to slash PRoot's syscall overhead. |
| TAWCROOT | Single-process seccomp backend compiled from pinned upstream source (actively hardened). |
Running the real Pi SDK via a typed, backpressured, epoch-isolated Node.js SDK Host means ~85% of every upstream Pi release lands automatically:
- Pi
1.6.0ready: GPT-6.2 Sol & Astra (default on OpenAI / Azure / Codex, auto-hiding unsupportedoffthinking), Qwen Token Plan new gateways & models, 1,698 chat models,undici 8.12.4(6 GHSA security fixes), Codex WebSocket & prompt-cache fixes. - Deep 1.6.0 host integration:
AgentSessionRuntime.takeUnreportedDiagnostics()(reports model fallbacks and extension errors once per occurrence on startup & session switches),commandOutput: "capture"(prevents git/npm subprocesses from corrupting protocol stdout or hanging on password prompts), OpenAI & Anthropic dropped-reasoning notices (showCacheMissNotices), and collapsed-stateimageUnsupportedByModelwarnings onreadcards. - Optimized cold start & live telemetry: loads
dist/bundle/index.jsfirst, defershttp-dispatcher/undiciunless custom proxy or timeouts are configured, embeds initial state directly insession.open, uses APK-stamp fast-paths to skip redundant per-boot asset hashing, and streams live context usage, token counts, and costs directly fromstateStore.
- Borderless tonal stream: clean tonal tool cards (subtle accent border only while running), quiet single-line thinking pill, intra-line word diffs, LaTeX math, Mermaid diagrams, and full-screen image viewer.
- 100% Official Pi Theme compatibility: full
okhsl()/oklch()support with automatic foreground contrast computation — zero hardcoded white text, drop in any desktop Pi theme JSON and it looks sharp in both light and dark modes. - Multi-source attachments & OOM-safe downsampling: gallery multi-pick, documents multi-pick, clipboard image paste, and
@workspace mentions — withcomputeSafeSampleSize()preventing 108MP camera OOMs and enforcing per-modelinputLimits.images.maxPerMessage. - Lean RAM & buttery scrolling: SHA-256 compact image cache keys (99.999% key RAM reduction, 5–10× effective capacity), centralized
PiMemoryTrimmerwired toonTrimMemory(), zero 60–120fps idle composer recompositions, and GPU-layer animations.
- Rule-by-rule
/treeport: all 5 official filter modes, collapsible subtrees, in-tree search, active-branch-first layout, and clean forking from any entry. - Incremental-indexed
/resume: persistent.session-list-index.json, workspace grouping, instant startup display, and seamless full-text relevance search across all projects.
Turn your phone into an agent peripheral only when you want to (设置 → 设备能力):
- 3 clean groups: Screen Automation (Accessibility), System & Hardware (Notifications, Clipboard, Location, Camera, App control), and Device Shell (Shizuku).
- 2×2 live permission readiness tiles + one-tap "Disable All".
- Zero-token & fail-safe: disabled tools are never exposed to the model (0 tokens); irreversible actions (
pm uninstall,pm clear,dd, force-stopping apps) always trigger a native 3-choice confirmation dialog.
| Requirement | Support |
|---|---|
| Android | 8.0 (API 26) or later |
| ABI | ARM64 (arm64-v8a) |
| Root / Termux | Not required |
| In-place upgrades | Consistent sideload signature — install newer APKs right over older versions |
- Download the latest
pi-android-*-sideload28-arm64.apkfrom GitHub Releases. - Install & launch; wait for first-boot runtime provisioning.
- Connect a provider in 设置 → 模型与供应商 (OAuth subscription login, API key, or custom OpenAI-compatible endpoint).
- Pick any folder on your phone and start coding with your agent.
flowchart TB
A["Android App (Kotlin · Jetpack Compose · Material 3)"]
B["Chat Stream · Workspace · Session Tree · Virtual TUI Surfaces"]
C["Kotlin Host Client & Live State Store"]
D["Typed JSONL Protocol (seq · epoch · backpressure)"]
E["Node.js SDK Host (app/src/main/assets/guest/sdk-host)"]
F["@earendil-works/pi-coding-agent 1.6.0 SDK"]
G["Built-in Tools · Extensions · MCP · Code Mode · Models"]
H["Runtime Manager (PRoot · Proroot · TAWCROOT)"]
L["Bundled Ubuntu 24.04 ARM64 · Node 24.22.1 · Git · rg · fd"]
A --> B
B --> C
C <--> D
D <--> E
E --> F
F --> G
E --> H
H --> L
- 307 real-SDK host checks + 6/6 CI: every push verifies
:protocolJVM tests, real Pi SDK contract (contract.mjs), 3× SDK Host suites (bundle,--no-bundle,--scandir-fix), Android API & i18n parity static guards, TAWCROOT NDK build, and both signed APKs (sideload28+modern36). - Automated upstream upgrade auditing: run
node tools/pi-upgrade-audit.mjsto scan all 9 host & app integration seams whenever upstream Pi publishes a release (full SOP indocs/sdk-host/upgrading.md).
git clone https://github.com/heikeyangle-code/pi-android.git
cd pi-android
node tools/pi-upgrade-audit.mjs --check-only
node tools/sdk-host/contract.mjs
node tools/sdk-host/test.mjs
./gradlew :protocol:test
node tools/fetch-runtime.mjs
./gradlew :app:assembleReleaseDocs: architecture.md · protocol.md · upgrading.md · runtime-engines.md
- What green CI proves: compilation, real Pi 1.6.0 SDK contract & behavior parity, and clean signed APK assembly; hardware-level runtime switching and Android permissions are verified on real devices.
- Interface language: full English & Simplified Chinese bilingual UI — follows your Android system language by default and switches instantly without restart under Settings → Appearance → Language.
- Star & Contribute: if you've ever wanted a real Linux coding agent in your pocket, drop a Star — issues, device reports, and PRs are all welcome!
Built on Pi Coding Agent · Node.js · Ubuntu · PRoot (Termux) · Proroot · TAWCROOT (MIT, © Sophie Winter) · ripgrep · fd · JetBrains Mono · Source Han Serif CN.
App source code is MIT licensed. Bundled third-party components retain their respective upstream licenses; full texts and notices ship in app/src/main/assets/licenses/.



