Initial Pocket Pi POC

Single-APK Android wrapper for the Pi coding agent. Bundles a Termux
runtime, the @earendil-works/pi-coding-agent engine, the e9n pi-mobile
PWA + pi-webserver, and a small set of Pi extensions. Native Compose
ModalBottomSheet exposes API keys / AGENTS.md / models.json / Restart
Pi / Re-run setup so non-technical users can configure the agent
without touching a shell.

Targets aarch64 phones. applicationId = com.termux for v0.1 so the
upstream Termux bootstrap binaries (which bake in /data/data/com.termux
/files/usr) work without recompiling.

POC scope; whether to keep this Termux-fork approach or rewrite as a
native Android client is the open question this build is meant to
inform.

Author: billeasydeveloper

.github/workflows/build-apk.yml

@@ -0,0 +1,71 @@
+# GitHub Actions: build Pocket Pi APK end-to-end.
+# Runs on every push to main and on tags `v*`. Tagged builds upload the APK
+# as a Release artifact.
+
+name: build-apk
+
+on:
+  push:
+    branches: [main]
+    tags:     ["v*"]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up JDK 17
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: 17
+
+      - name: Set up Android SDK
+        uses: android-actions/setup-android@v3
+
+      - name: Set up Node 20 + pnpm
+        uses: actions/setup-node@v4
+        with: { node-version: "20" }
+      - uses: pnpm/action-setup@v4
+        with: { version: 9 }
+
+      - name: Build TS extensions
+        run: |
+          cd extensions/pi-termux-tools && pnpm install && pnpm build && cd -
+          cd extensions/pi-skill-learner && pnpm install && pnpm build && cd -
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - name: Build Python wheel
+        run: |
+          python -m pip install --upgrade pip build
+          cd python/skill_learner_dspy && python -m build --wheel
+
+      - name: Build bootstrap zip (aarch64)
+        run: |
+          chmod +x bootstrap/build-bootstrap.sh bootstrap/postinstall.sh bootstrap/patches/*.sh
+          ./bootstrap/build-bootstrap.sh aarch64
+
+      - name: Build debug APK
+        working-directory: android
+        run: ./gradlew --no-daemon assembleDebug
+
+      - name: Build release APK (unsigned)
+        working-directory: android
+        run: ./gradlew --no-daemon assembleRelease || true
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: pocket-pi-debug-apk
+          path: android/app/build/outputs/apk/debug/app-debug.apk
+
+      - name: Attach to Release
+        if: startsWith(github.ref, 'refs/tags/v')
+        uses: softprops/action-gh-release@v2
+        with:
+          files: android/app/build/outputs/apk/debug/app-debug.apk

.gitignore

@@ -0,0 +1,40 @@
+# Node
+node_modules/
+dist/
+*.tsbuildinfo
+.npmrc
+
+# Python
+__pycache__/
+*.pyc
+*.egg-info/
+build/
+.venv/
+venv/
+
+# Android
+.gradle/
+local.properties
+captures/
+*.iml
+.idea/
+android/app/build/
+android/build/
+android/.cxx/
+android/.kotlin/
+
+# Local tooling state
+.claude/
+
+# Bootstrap output + upstream Termux clone (fetched on demand by rebuild-with-prefix.sh)
+bootstrap/dist/
+bootstrap/work/
+bootstrap/termux-packages/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Editor
+.vscode/
+*.swp

LICENSE

@@ -0,0 +1,28 @@
+MIT License
+
+Copyright (c) 2026 CelestialCreator
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Third-party components fetched at build/runtime keep their own licenses, including:
+- Termux bootstrap binaries — https://github.com/termux/termux-packages (GPL-3.0)
+- Pi coding agent — https://github.com/earendil-works/pi (MIT)
+- pi-mobile / pi-webserver — https://github.com/espennilsen/pi (MIT)

README.md

@@ -0,0 +1,92 @@
+# Pocket Pi
+
+A [Pi coding agent](https://pi.dev/) shipped as an Android APK. No Termux install, no shell setup — install the APK, paste an LLM key, chat.
+
+> POC, fast-tracked. We bundle Termux's Linux runtime inside an Android app so the team can try a single-tap Pi install on a phone. Whether this approach is worth productizing (vs. building a proper native Android client) is the open question — that's what the POC is for.
+
+## Install (team testers)
+
+1. Grab the latest APK from the [Releases page](https://github.com/CelestialCreator/pocket-pi/releases/latest).
+2. Sideload — tap the APK on the phone (allow install from unknown sources for your browser/file manager), or `adb install pocket-pi-vX.Y.Z.apk`.
+3. Open the app. First launch runs the bootstrap (3–5 min on Wi-Fi: extracts Termux, installs Node + npm packages, registers Pi extensions).
+4. When you see "Send a message to your Pi agent" — tap the ⚙ at the top right.
+5. Paste at least one provider API key (NVIDIA NIM is free; OpenRouter / OpenAI / Anthropic / Groq also wired up), then tap **Save keys** → **Restart Pi**.
+6. Tap **Re-run setup** once if extensions are missing (it's idempotent and safe).
+7. Chat away.
+
+If anything wedges, tap **⚙ → Re-run setup**. As a last resort, force-stop the app from Android Settings and reopen — the install state on disk is preserved.
+
+## What's inside
+
+| Layer | Component |
+|---|---|
+| App shell | Android (Kotlin + Jetpack Compose) — `android/` |
+| Linux runtime | Termux bootstrap (Node 25, Python, git, ripgrep, openssl) — `bootstrap/` |
+| Chat UI | [`@e9n/pi-mobile`](https://www.npmjs.com/package/@e9n/pi-mobile) PWA served by [`@e9n/pi-webserver`](https://www.npmjs.com/package/@e9n/pi-webserver), rendered in a WebView |
+| Agent engine | [`@earendil-works/pi-coding-agent`](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) |
+| Pi extensions | `pi-web-access`, `pi-subagents`, `oh-pi`, `@aliou/pi-guardrails`, `pi-mcp-adapter`, `pk-pi-hermes-evolve` |
+| Native config | Compose `ModalBottomSheet` with sections for API keys, AGENTS.md, models.json, Restart Pi, Re-run setup |
+| Providers wired | NVIDIA NIM (free), OpenRouter, OpenAI, Anthropic, Groq — keys go to `~/.config/<provider>/api-key`; the model registry lives in `~/.pi/agent/models.json` |
+
+## Repo layout
+
+```
+.
+├── android/                  Gradle Android project for the APK
+├── bootstrap/                Termux bootstrap zip generator + postinstall
+│   ├── build-bootstrap.sh     Layer our payload on upstream Termux's aarch64 zip
+│   ├── postinstall.sh         First-run install: apt, npm, pip, pi install loop
+│   ├── npm-packages.txt       Pi engine + extensions + peer deps
+│   ├── packages.txt           Termux apt packages
+│   ├── pip-packages.txt       Python deps (dspy etc, best-effort)
+│   └── patches/               One-shot post-update patches (e.g. hermes-evolve)
+├── config/                   Baked into the bootstrap at build time
+│   ├── AGENTS.md              Always-on Pi context
+│   ├── models.json            Provider/model registry (NVIDIA pre-filled)
+│   └── claude-bridge.json     Wrapper config (legacy; not active)
+├── extensions/               Our own Pi extensions (TypeScript)
+│   ├── pi-termux-tools/       Phone surface tools (TTS, notify, share, camera)
+│   └── pi-skill-learner/      Hermes-style learning loop
+├── python/skill_learner_dspy DSPy reflection backend
+├── skills/                   Pi Skills bundled into the bootstrap
+└── scripts/                  Misc dev helpers
+```
+
+## Build from source
+
+```bash
+# 1. Bootstrap zip (produces bootstrap/dist/bootstrap-aarch64.zip, ~30M)
+cd bootstrap && ./build-bootstrap.sh aarch64
+
+# 2. (Optional) the custom Pi extensions
+cd ../extensions/pi-termux-tools && pnpm install && pnpm build
+cd ../pi-skill-learner       && pnpm install && pnpm build
+
+# 3. APK
+cd ../../android && ./gradlew :app:assembleDebug
+# Output: android/app/build/outputs/apk/debug/app-debug.apk (~67 MB)
+```
+
+The current build uses `applicationId = com.termux` so the upstream Termux bootstrap binaries (which bake in the path `/data/data/com.termux/files/usr`) work without recompiling. To ship under a real app id, run `bootstrap/rebuild-with-prefix.sh` (Docker, 4–12 h on Apple Silicon) to produce a bootstrap pinned to a custom prefix, then flip `applicationId` in `android/app/build.gradle.kts`.
+
+## What works / what doesn't (v0.1)
+
+| | Status |
+|---|---|
+| Single-APK install on aarch64 phones | ✓ |
+| 8 Pi extensions registered, 17 tools online | ✓ |
+| NVIDIA NIM + OpenRouter end-to-end (chat, tool use, cost tracking) | ✓ |
+| Native ⚙ Config sheet — keys, AGENTS.md, models.json, restart, re-run setup | ✓ |
+| Recovery UI when pi-webserver doesn't bind within 15s | ✓ |
+| Slash commands `/session`, `/clear`, `/model`, `/threads` intercepted client-side | not yet — currently sent to LLM as text |
+| Chat history persistence across tab switches | not yet — JSONL on disk, no resume |
+| `applicationId` ≠ `com.termux` | not yet — requires custom bootstrap rebuild |
+| Cosmetic phantom-icon row on some Android WebView builds | accepted — known compositor artifact, no functional impact |
+
+## License
+
+MIT. Third-party runtime components keep their own licenses (Termux GPL, Pi MIT) — see `LICENSE` for the list.
+
+## Status
+
+v0.1 — POC. The Termux-fork-inside-an-APK approach works. Whether to invest in productizing it (custom prefix bootstrap, real applicationId, signed release builds, Play Store, etc.) or rewrite this as a proper native Android client that talks to Pi over the network is the question this POC is meant to inform.

android/.gitignore

@@ -0,0 +1,8 @@
+.gradle/
+build/
+.idea/
+local.properties
+*.iml
+captures/
+.cxx/
+app/build/

android/app/build.gradle.kts

@@ -0,0 +1,78 @@
+plugins {
+    alias(libs.plugins.android.application)
+    alias(libs.plugins.kotlin.android)
+    alias(libs.plugins.kotlin.compose)
+    alias(libs.plugins.kotlin.serialization)
+}
+
+android {
+    namespace = "com.zosma.pocketpi"
+    compileSdk = 34
+
+    defaultConfig {
+        // TEMP for emulator validation. The upstream Termux bootstrap zip
+        // ships compiled binaries (apt, dpkg, busybox helpers) with the path
+        // /data/data/com.termux/files/usr baked in. Until we rebuild a
+        // custom bootstrap pinned to our real prefix, run as com.termux so
+        // that Android's chosen filesDir matches what the binaries expect.
+        // Production build: applicationId = "com.zosma.pocketpi" + a custom
+        // bootstrap built via termux-packages/scripts/build-bootstraps.sh.
+        applicationId = "com.termux"
+        minSdk = 24
+        // CRITICAL: Termux itself caps targetSdk at 28. Android 10+ enforces
+        // W^X on the app's private data directory when targetSdk >= 29 — any
+        // execve() of a file under /data/user/0/<pkg>/files/ is blocked with
+        // EACCES regardless of file mode bits. Capping at 28 keeps the
+        // legacy semantics that allow exec from app-data, which Pi (and the
+        // entire Termux runtime) relies on.
+        targetSdk = 28
+        versionCode = 1
+        versionName = "0.1.0"
+
+        ndk { abiFilters += listOf("arm64-v8a") }
+    }
+
+    // Pocket Pi mirrors Termux's install layout — the bootstrap zip extracts
+    // into /data/data/com.zosma.pocketpi/files/usr at first launch.
+    buildTypes {
+        release {
+            isMinifyEnabled = false
+            proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro")
+        }
+        debug { /* defaults */ }
+    }
+
+    // Ship the bootstrap zip as a raw asset; PocketPiBootstrap unzips on first
+    // run. The build script in bootstrap/build-bootstrap.sh produces this.
+    sourceSets["main"].assets.srcDir("../../bootstrap/dist")
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+    kotlinOptions { jvmTarget = "17" }
+
+    packaging {
+        resources.excludes += listOf("/META-INF/{AL2.0,LGPL2.1}", "/META-INF/INDEX.LIST")
+        // Required when AndroidManifest sets extractNativeLibs="true". Pocket
+        // Pi needs that flag so .so files end up in nativeLibraryDir with
+        // executable permission, which is the only reliable way to ship
+        // executables to the device on Android 6+.
+        jniLibs.useLegacyPackaging = true
+    }
+}
+
+dependencies {
+    implementation(libs.androidx.core.ktx)
+    implementation(libs.androidx.lifecycle.runtime)
+    implementation(libs.androidx.activity.compose)
+    implementation(platform(libs.androidx.compose.bom))
+    implementation(libs.androidx.ui)
+    implementation(libs.androidx.ui.graphics)
+    implementation(libs.androidx.ui.tooling.preview)
+    implementation(libs.androidx.material3)
+    implementation(libs.androidx.datastore)
+    implementation(libs.androidx.work)
+    implementation(libs.kotlinx.serialization.json)
+    implementation(libs.kotlinx.coroutines.android)
+}

android/app/proguard-rules.pro

@@ -0,0 +1,4 @@
+# Pocket Pi proguard rules.
+# Compose / Material handle their own keep rules via the Compose plugin.
+-keep class kotlinx.serialization.** { *; }
+-keepclassmembers,allowshrinking class kotlinx.serialization.** { *; }

android/app/src/main/AndroidManifest.xml

@@ -0,0 +1,57 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:tools="http://schemas.android.com/tools">
+
+    <uses-permission android:name="android.permission.INTERNET" />
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />
+    <uses-permission android:name="android.permission.WAKE_LOCK" />
+    <uses-permission android:name="android.permission.RECORD_AUDIO" />
+    <uses-permission android:name="android.permission.CAMERA" />
+    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
+    <uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
+    <uses-permission android:name="android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS" />
+
+    <application
+        android:name=".PocketPiApp"
+        android:label="@string/app_name"
+        android:icon="@mipmap/ic_launcher"
+        android:roundIcon="@mipmap/ic_launcher_round"
+        android:theme="@style/Theme.PocketPi"
+        android:supportsRtl="true"
+        android:allowBackup="false"
+        android:requestLegacyExternalStorage="false"
+        android:extractNativeLibs="true"
+        android:networkSecurityConfig="@xml/network_security_config"
+        tools:targetApi="34"
+        tools:replace="android:extractNativeLibs">
+
+        <activity
+            android:name=".MainActivity"
+            android:exported="true"
+            android:windowSoftInputMode="adjustResize"
+            android:theme="@style/Theme.PocketPi">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.LAUNCHER" />
+            </intent-filter>
+        </activity>
+
+
+        <service
+            android:name=".service.PocketPiService"
+            android:exported="false"
+            android:foregroundServiceType="dataSync" />
+
+        <provider
+            android:name="androidx.core.content.FileProvider"
+            android:authorities="${applicationId}.fileprovider"
+            android:exported="false"
+            android:grantUriPermissions="true">
+            <meta-data
+                android:name="android.support.FILE_PROVIDER_PATHS"
+                android:resource="@xml/file_paths" />
+        </provider>
+    </application>
+</manifest>