From ad8026f8216aecef0f3dbfff39258c0aa106dfa5 Mon Sep 17 00:00:00 2001 From: Mario Zechner Date: Mon, 2 Feb 2026 00:09:17 +0100 Subject: [PATCH] docs(coding-agent): add Termux setup guide and changelog audit - Add comprehensive Termux (Android) setup documentation - Add Termux platform detection in tools-manager for fd/rg - Add New Features entries for Android/Termux, bash spawn hook, Linux ARM64 musl - Add missing changelog entry for clipboard dependency update --- packages/coding-agent/CHANGELOG.md | 11 ++ packages/coding-agent/README.md | 2 +- packages/coding-agent/docs/termux.md | 127 ++++++++++++++++++ .../coding-agent/src/utils/tools-manager.ts | 16 +++ 4 files changed, 155 insertions(+), 1 deletion(-) create mode 100644 packages/coding-agent/docs/termux.md diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md index 3a652973..453a3425 100644 --- a/packages/coding-agent/CHANGELOG.md +++ b/packages/coding-agent/CHANGELOG.md @@ -4,6 +4,16 @@ ### New Features +- **Android/Termux support**: Pi now runs on Android via Termux. Install with: + ```bash + pkg install nodejs termux-api git + npm install -g @mariozechner/pi-coding-agent + mkdir -p ~/.pi/agent + echo "You are running on Android in Termux." > ~/.pi/agent/AGENTS.md + ``` + Clipboard operations fall back gracefully when `termux-api` is unavailable. ([#1164](https://github.com/badlogic/pi-mono/issues/1164)) +- **Bash spawn hook**: Extensions can now intercept and modify bash commands before execution via `pi.setBashSpawnHook()`. Adjust the command string, working directory, or environment variables. See [docs/extensions.md](docs/extensions.md). ([#1160](https://github.com/badlogic/pi-mono/pull/1160) by [@mitsuhiko](https://github.com/mitsuhiko)) +- **Linux ARM64 musl support**: Pi now runs on Alpine Linux ARM64 (linux-arm64-musl) via updated clipboard dependency. - **Nix/Guix support**: `PI_PACKAGE_DIR` environment variable overrides the package path for content-addressed package managers where store paths tokenize poorly. See [README.md#environment-variables](README.md#environment-variables). ([#1153](https://github.com/badlogic/pi-mono/pull/1153) by [@odysseus0](https://github.com/odysseus0)) - **Named session filter**: `/resume` picker now supports filtering to show only named sessions via Ctrl+N. Configurable via `toggleSessionNamedFilter` keybinding. See [docs/keybindings.md](docs/keybindings.md). ([#1128](https://github.com/badlogic/pi-mono/pull/1128) by [@w-winter](https://github.com/w-winter)) - **Typed tool call events**: Extension developers can narrow `ToolCallEvent` types using `isToolCallEventType()` for better TypeScript support. See [docs/extensions.md#tool-call-events](docs/extensions.md#tool-call-events). ([#1147](https://github.com/badlogic/pi-mono/pull/1147) by [@giuseppeg](https://github.com/giuseppeg)) @@ -11,6 +21,7 @@ ### Added +- Added Linux ARM64 musl (Alpine Linux) support via clipboard dependency update - Added Android/Termux support with graceful clipboard fallback ([#1164](https://github.com/badlogic/pi-mono/issues/1164)) - Added bash tool spawn hook support for adjusting command, cwd, and env before execution ([#1160](https://github.com/badlogic/pi-mono/pull/1160) by [@mitsuhiko](https://github.com/mitsuhiko)) - Added typed `ToolCallEvent.input` per tool with `isToolCallEventType()` type guard for narrowing built-in tool events ([#1147](https://github.com/badlogic/pi-mono/pull/1147) by [@giuseppeg](https://github.com/giuseppeg)) diff --git a/packages/coding-agent/README.md b/packages/coding-agent/README.md index cbe79bf2..e07ace6c 100644 --- a/packages/coding-agent/README.md +++ b/packages/coding-agent/README.md @@ -63,7 +63,7 @@ pi Then just talk to pi. By default, pi gives the model four tools: `read`, `write`, `edit`, and `bash`. The model uses these to fulfill your requests. Add capabilities via [skills](#skills), [prompt templates](#prompt-templates), [extensions](#extensions), or [pi packages](#pi-packages). -**Platform notes:** [Windows](docs/windows.md) | [Terminal setup](docs/terminal-setup.md) | [Shell aliases](docs/shell-aliases.md) +**Platform notes:** [Windows](docs/windows.md) | [Termux (Android)](docs/termux.md) | [Terminal setup](docs/terminal-setup.md) | [Shell aliases](docs/shell-aliases.md) --- diff --git a/packages/coding-agent/docs/termux.md b/packages/coding-agent/docs/termux.md new file mode 100644 index 00000000..200b00fe --- /dev/null +++ b/packages/coding-agent/docs/termux.md @@ -0,0 +1,127 @@ +# Termux (Android) Setup + +Pi runs on Android via [Termux](https://termux.dev/), a terminal emulator and Linux environment for Android. + +## Prerequisites + +1. Install [Termux](https://github.com/termux/termux-app#installation) from GitHub or F-Droid (not Google Play, that version is deprecated) +2. Install [Termux:API](https://github.com/termux/termux-api#installation) from GitHub or F-Droid for clipboard and other device integrations + +## Installation + +```bash +# Update packages +pkg update && pkg upgrade + +# Install dependencies +pkg install nodejs termux-api git + +# Install pi +npm install -g @mariozechner/pi-coding-agent + +# Create config directory +mkdir -p ~/.pi/agent + +# Run pi +pi +``` + +## Clipboard Support + +Clipboard operations use `termux-clipboard-set` and `termux-clipboard-get` when running in Termux. The Termux:API app must be installed for these to work. + +Image clipboard is not supported on Termux (the `ctrl+v` image paste feature will not work). + +## Example AGENTS.md for Termux + +Create `~/.pi/agent/AGENTS.md` to help the agent understand the Termux environment: + +```markdown +# Agent Environment: Termux on Android + +## Location +- **OS**: Android (Termux terminal emulator) +- **Home**: `/data/data/com.termux/files/home` +- **Prefix**: `/data/data/com.termux/files/usr` +- **Shared storage**: `/storage/emulated/0` (Downloads, Documents, etc.) + +## Opening URLs +```bash +termux-open-url "https://example.com" +``` + +## Opening Files +```bash +termux-open file.pdf # Opens with default app +termux-open -c image.jpg # Choose app +``` + +## Clipboard +```bash +termux-clipboard-set "text" # Copy +termux-clipboard-get # Paste +``` + +## Notifications +```bash +termux-notification -t "Title" -c "Content" +``` + +## Device Info +```bash +termux-battery-status # Battery info +termux-wifi-connectioninfo # WiFi info +termux-telephony-deviceinfo # Device info +``` + +## Sharing +```bash +termux-share -a send file.txt # Share file +``` + +## Other Useful Commands +```bash +termux-toast "message" # Quick toast popup +termux-vibrate # Vibrate device +termux-tts-speak "hello" # Text to speech +termux-camera-photo out.jpg # Take photo +``` + +## Notes +- Termux:API app must be installed for `termux-*` commands +- Use `pkg install termux-api` for the command-line tools +- Storage permission needed for `/storage/emulated/0` access +``` + +## Limitations + +- **No image clipboard**: Termux clipboard API only supports text +- **No native binaries**: Some optional native dependencies (like the clipboard module) are unavailable on Android ARM64 and are skipped during installation +- **Storage access**: To access files in `/storage/emulated/0` (Downloads, etc.), run `termux-setup-storage` once to grant permissions + +## Troubleshooting + +### Clipboard not working + +Ensure both apps are installed: +1. Termux (from GitHub or F-Droid) +2. Termux:API (from GitHub or F-Droid) + +Then install the CLI tools: +```bash +pkg install termux-api +``` + +### Permission denied for shared storage + +Run once to grant storage permissions: +```bash +termux-setup-storage +``` + +### Node.js installation issues + +If npm fails, try clearing the cache: +```bash +npm cache clean --force +``` diff --git a/packages/coding-agent/src/utils/tools-manager.ts b/packages/coding-agent/src/utils/tools-manager.ts index ebb4ca10..53d2c513 100644 --- a/packages/coding-agent/src/utils/tools-manager.ts +++ b/packages/coding-agent/src/utils/tools-manager.ts @@ -182,6 +182,12 @@ async function downloadTool(tool: "fd" | "rg"): Promise { return binaryPath; } +// Termux package names for tools +const TERMUX_PACKAGES: Record = { + fd: "fd-find", + rg: "ripgrep", +}; + // Ensure a tool is available, downloading if necessary // Returns the path to the tool, or null if unavailable export async function ensureTool(tool: "fd" | "rg", silent: boolean = false): Promise { @@ -193,6 +199,16 @@ export async function ensureTool(tool: "fd" | "rg", silent: boolean = false): Pr const config = TOOLS[tool]; if (!config) return undefined; + // On Android/Termux, Linux binaries don't work due to Bionic libc incompatibility. + // Users must install via pkg. + if (platform() === "android") { + const pkgName = TERMUX_PACKAGES[tool] ?? tool; + if (!silent) { + console.log(chalk.yellow(`${config.name} not found. Install with: pkg install ${pkgName}`)); + } + return undefined; + } + // Tool not found - download it if (!silent) { console.log(chalk.dim(`${config.name} not found. Downloading...`));