Skip to content

termux.md

Latest commit

 

History

History
117 lines (73 loc) · 3.51 KB

termux.md

File metadata and controls

117 lines (73 loc) · 3.51 KB
Raw

Run Pi on Android with Termux

Pi runs on Android through Termux, a terminal emulator and Linux environment. Text input, file tools, and shell commands are supported. Pi can copy and paste text through the Android clipboard with Termux:API. Clipboard image paste is not supported.

Before you begin

Install Termux from GitHub or F-Droid. Do not use the deprecated Google Play build.

Termux:API is optional. Install it only when you want Pi to copy or paste Android clipboard text, or when shell commands need Android device APIs.

Install Pi

  1. Update Termux packages:

    pkg update && pkg upgrade

  2. Install Node.js and Git:

    pkg install nodejs git

  3. Install Pi:

    npm install -g --ignore-scripts @earendil-works/pi-coding-agent

  4. Verify the installation:

    pi --version

  5. Open the folder you want to work in and start Pi:

    cd /path/to/working-folder
pi

Continue with the main Quickstart to connect a model and run your first task.

Access Android shared storage

Termux cannot access shared Android storage until you grant permission. Run this once:

termux-setup-storage

After approval, Android shared storage is available under /storage/emulated/0 and through the links Termux creates under ~/storage/.

Only grant this permission when Pi should be able to access those files. Commands and tools running in Termux use the same storage permissions as the Termux process.

Use clipboard commands

Pi uses termux-clipboard-set to copy text and termux-clipboard-get for its clipboard-paste shortcut. Shell commands can use both commands directly. Install the Termux:API app and its command-line package:

pkg install termux-api

Verify the integration:

printf 'Pi clipboard test' | termux-clipboard-set
termux-clipboard-get

The second command should print Pi clipboard test.

The Termux clipboard API supports text only. Pi's clipboard-paste shortcut inserts that text into the editor but cannot attach clipboard images.

Add Termux-specific instructions

Pi detects that it is running in Termux, but it cannot infer how you want it to interact with Android. Add only the environment details relevant to your work to ~/.pi/agent/AGENTS.md:

# Termux environment

- Pi runs in Termux on Android.
- Shared Android storage is under `/storage/emulated/0`.
- Open URLs with `termux-open-url "https://example.com"`.
- Open files with `termux-open <path>`.
- Do not access shared storage unless the task requires it.

Run /reload after changing the file during an active session.

Troubleshooting

Clipboard integration fails

Confirm that you installed both components:

  1. The Termux:API Android app from the same source as Termux
  2. The termux-api command-line package

Then run the clipboard verification commands above outside Pi. If they fail there, fix the Termux:API installation before retrying Pi's copy command.

Shared storage reports permission denied

Run termux-setup-storage, approve the Android permission request, and retry the path under ~/storage/ or /storage/emulated/0.

Pi is not found after installation

Open a new Termux shell and run:

npm prefix -g
command -v pi

Confirm that the global npm binary directory is on PATH, then reinstall Pi if the package is missing.