Android / Termux Environment Constraints
Scope and when this applies. These constraints apply when you are executing inside Termux on Android, regardless of how Claude Code itself was packaged. The load-bearing runtime signal is $PREFIX === "/data/data/com.termux/files/usr". If that environment variable points at Termux's prefix, you are in Termux and these constraints apply, even if process.platform reports "linux" (it will report "linux" if Claude Code was installed via this repo's v2.9.0 Path A, which runs the linux-arm64 binary patched via glibc-runner; it will report "android" only on older Path A v2.x installs that used the JS bundle). If $PREFIX is unset or points at /usr, you are inside a chroot-like sandbox (for example, a Linux rootfs running under proot-distro, Path B) or inside a hypervisor-managed Linux VM (Path C), and standard Linux conventions apply; most of this file does not.
If the runtime signals indicate the in-Termux case, the constraints below produce silent failures, not errors. Every suggestion must account for them.
Hard Rules: Never Suggest These
- No
sudo. Root does not exist. No su, no doas, no privilege escalation of any kind.
- No
systemctl or systemd. Android does not use systemd. No journalctl, no service, no unit files.
- No standard Linux paths.
/usr/bin, /etc, /var do not exist or are not writable. Termux paths:
- Home:
/data/data/com.termux/files/home
- Prefix:
/data/data/com.termux/files/usr
- Binaries:
$PREFIX/bin
- Config:
$PREFIX/etc
- No ports below 1024. No root = no binding to 80, 443, etc. Use 1024+.
- Prefer
pkg over apt. Both work, but pkg auto-updates the package index before installing.
- No Docker, no containers. The kernel does not support them without root.
Silent Failure Modes
- Node.js is not required by this repo's
install.sh. The patched linux-arm64 claude binary is self-contained. If Node is installed separately on native Termux, prefer v25+: v24 had a documented startup hang on ARM64 that was resolved in v25.
- File descriptor limits vary by device. Check with
ulimit -n. Avoid spawning many concurrent processes.
- Android phantom process killer limits background processes to ~32 across all apps. If "Disable child process restrictions" is enabled in Developer Options, this limit is lifted; 6 concurrent subagents have been observed stable in testing. Otherwise limit to 2-3.
process.platform reporting varies by install path. On Path A v2.9.0 (the linux-arm64 binary patched via glibc-runner), Node.js reports process.platform === "linux" even though you are inside Termux. On older Path A v2.x (the JS-bundle npm install) it reports "android". On Path B (proot-distro Ubuntu) and Path C (AVF), it reports "linux" and you are not in Termux. The reliable cross-path signal that you are still in Termux is $PREFIX === "/data/data/com.termux/files/usr".
Package Installation
Prefer pkg (auto-updates the index before install). apt and apt-get also work but skip the auto-update:
pkg install <package> -y
pkg upgrade
pkg search <query>
When Unsure
If you're about to suggest a command that assumes standard Linux, stop and verify it works on Termux first. When in doubt, prefix with command -v <tool> >/dev/null 2>&1 to check availability.
1---2name: termux-safe3description: Android/Termux constraints reference. Prevents Claude Code from suggesting commands that fail silently on Android (sudo, systemd, non-Termux paths, etc.).4---56# Android / Termux Environment Constraints78> **Scope and when this applies.** These constraints apply when you are executing inside Termux on Android, regardless of how Claude Code itself was packaged. The load-bearing runtime signal is `$PREFIX === "/data/data/com.termux/files/usr"`. If that environment variable points at Termux's prefix, you are in Termux and these constraints apply, even if `process.platform` reports `"linux"` (it will report `"linux"` if Claude Code was installed via this repo's v2.9.0 Path A, which runs the linux-arm64 binary patched via glibc-runner; it will report `"android"` only on older Path A v2.x installs that used the JS bundle). If `$PREFIX` is unset or points at `/usr`, you are inside a chroot-like sandbox (for example, a Linux rootfs running under `proot-distro`, Path B) or inside a hypervisor-managed Linux VM (Path C), and standard Linux conventions apply; most of this file does not.910If the runtime signals indicate the in-Termux case, the constraints below produce **silent failures, not errors.** Every suggestion must account for them.1112## Hard Rules: Never Suggest These1314- **No `sudo`.** Root does not exist. No `su`, no `doas`, no privilege escalation of any kind.15- **No `systemctl` or `systemd`.** Android does not use systemd. No `journalctl`, no `service`, no unit files.16- **No standard Linux paths.** `/usr/bin`, `/etc`, `/var` do not exist or are not writable. Termux paths:17 - Home: `/data/data/com.termux/files/home`18 - Prefix: `/data/data/com.termux/files/usr`19 - Binaries: `$PREFIX/bin`20 - Config: `$PREFIX/etc`21- **No ports below 1024.** No root = no binding to 80, 443, etc. Use 1024+.22- **Prefer `pkg` over `apt`.** Both work, but `pkg` auto-updates the package index before installing.23- **No Docker, no containers.** The kernel does not support them without root.2425## Silent Failure Modes2627- **Node.js is not required by this repo's `install.sh`.** The patched linux-arm64 claude binary is self-contained. If Node is installed separately on native Termux, prefer v25+: v24 had a documented startup hang on ARM64 that was resolved in v25.28- **File descriptor limits vary by device.** Check with `ulimit -n`. Avoid spawning many concurrent processes.29- **Android phantom process killer** limits background processes to ~32 across all apps. If "Disable child process restrictions" is enabled in Developer Options, this limit is lifted; 6 concurrent subagents have been observed stable in testing. Otherwise limit to 2-3.30- **`process.platform` reporting varies by install path.** On Path A v2.9.0 (the linux-arm64 binary patched via glibc-runner), Node.js reports `process.platform === "linux"` even though you are inside Termux. On older Path A v2.x (the JS-bundle npm install) it reports `"android"`. On Path B (proot-distro Ubuntu) and Path C (AVF), it reports `"linux"` and you are not in Termux. The reliable cross-path signal that you are still in Termux is `$PREFIX === "/data/data/com.termux/files/usr"`.3132## Package Installation3334Prefer `pkg` (auto-updates the index before install). `apt` and `apt-get` also work but skip the auto-update:35```bash36pkg install <package> -y37pkg upgrade38pkg search <query>39```4041## When Unsure4243If you're about to suggest a command that assumes standard Linux, stop and verify it works on Termux first. When in doubt, prefix with `command -v <tool> >/dev/null 2>&1` to check availability.
ferrumclaudepilgrim