mirror of
https://github.com/badlogic/pi-mono.git
synced 2026-11-05 23:37:25 +00:00
25cc5c7bf4
* docs(coding-agent): improve getting started documentation * docs(coding-agent): correct getting started details * docs(coding-agent): clarify SDK entry point * docs(coding-agent): restructure guides and references * docs(coding-agent): improve getting started guides * docs(coding-agent): refresh integration guides * docs(coding-agent): improve terminal and CLI guides * docs(coding-agent): refresh customisation guides * docs(coding-agent): clarify project trust terminology * docs(coding-agent): simplify customisation guidance * docs(coding-agent): improve runtime and reference guidance * Fix settings reference * feat(coding-agent): add Crowdin documentation sync * docs(coding-agent): separate CLI and slash command references * docs(coding-agent): correct compaction reference * docs(coding-agent): streamline package documentation * docs(coding-agent): split RPC reference documentation * Update configuration docs * Shorten config docs * docs(coding-agent): refine configuration references * docs(coding-agent): streamline settings reference * docs(coding-agent): clarify configuration reference * docs(coding-agent): clarify project trust exception * docs(coding-agent): simplify keybindings reference * docs(coding-agent): remove Crowdin integration * docs(coding-agent): turn themes reference into guide * docs(coding-agent): consolidate model and authentication docs * docs(tui): require Component.invalidate() (fixes #9358) * docs(coding-agent): document offline catalog behavior (fixes #8684) * docs(coding-agent): preserve established documentation routes * docs(coding-agent): reorganize documentation navigation * docs(coding-agent): correct audited behavior Clarify provider, session, local-model, Termux, TUI, SDK, debug, and extension behavior. Simplify the documentation audit to report only clear user-visible contradictions. * docs(coding-agent): fix broken documentation links
117 lines
3.5 KiB
Markdown
117 lines
3.5 KiB
Markdown
# Run Pi on Android with Termux
|
|
|
|
Pi runs on Android through [Termux](https://termux.dev/), 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](https://github.com/termux/termux-app#installation). Do not use the deprecated Google Play build.
|
|
|
|
[Termux:API](https://github.com/termux/termux-api#installation) 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:
|
|
|
|
```bash
|
|
pkg update && pkg upgrade
|
|
```
|
|
|
|
2. Install Node.js and Git:
|
|
|
|
```bash
|
|
pkg install nodejs git
|
|
```
|
|
|
|
3. Install Pi:
|
|
|
|
```bash
|
|
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
|
|
```
|
|
|
|
4. Verify the installation:
|
|
|
|
```bash
|
|
pi --version
|
|
```
|
|
|
|
5. Open the folder you want to work in and start Pi:
|
|
|
|
```bash
|
|
cd /path/to/working-folder
|
|
pi
|
|
```
|
|
|
|
Continue with the main [Quickstart](quickstart.md#3-choose-a-model) 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
pkg install termux-api
|
|
```
|
|
|
|
Verify the integration:
|
|
|
|
```bash
|
|
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`:
|
|
|
|
````markdown
|
|
# 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:
|
|
|
|
```bash
|
|
npm prefix -g
|
|
command -v pi
|
|
```
|
|
|
|
Confirm that the global npm binary directory is on `PATH`, then reinstall Pi if the package is missing.
|