termux-elite

termux-elite

Termux is not a normal Linux box, and your AI agent keeps forgetting that. termux-elite gives coding agents 15 short, tested playbooks for the things that actually break on a phone: glibc wheels that will not import, node-gyp looking for an NDK, processes Android kills with signal 9, /sdcard permissions, proot versus native, and more.

Each skill tells the agent what to inspect first, which layer is failing, what is safe to change, how to prove the fix worked, and when to hand off to a neighbouring skill.

npx skills add Alex72-py/termux-elite

Works with Claude Code, Codex, Gemini CLI, Cursor, OpenCode, Antigravity and the other agents the skills CLI supports. Host-specific options are below.

What changes for your agent

Without a playbook, an agent that sees pip install cryptography fail on a phone tends to retry, reach for sudo, or install a toolchain it did not need. With python-native-build loaded it is guided to:

1. Establish native Termux versus proot.
2. Capture Python version, pip location, architecture, and the first real compiler error.
3. Check whether a compatible wheel or a Termux-packaged library exists before building anything.
4. Explain and confirm any package or toolchain change.
5. Re-run the install and import a minimal module.
6. Report what changed and what is still unsupported on Android.

The skill is a procedure, not a command to run blindly. See examples/.

Find the skill by symptom

Agents do not need this table: each skill's description lists the same symptoms, and AGENTS.md and manifest.json carry a routing index with a risk level per skill.

Triage in one command

sh scripts/doctor.sh                       # run every read-only helper, print one report
sh scripts/doctor.sh --list                # show what it would run
sh scripts/doctor.sh --skill termux-network

It prints facts only and changes nothing. Paste the report to your agent, then follow the skill for whichever layer looks wrong (device and install source, package manager, toolchain, network, storage, git auth).

Safe by design

• Inspect before mutating. The first step of every skill is a cheap read-only check, and each skill ships a small helper script that only prints key: value facts.
• Environment first. The environment helper classifies the shell as native Termux, proot, another Android shell, or a non-Android system before any install, so an agent does not run Termux commands where they do not apply.
• Mutations are confirmed. Package installs, permission changes, config edits, and service changes are named explicitly and need confirmation. Medium-risk skills include a rollback.
• No secrets. Helpers redact credentials in URLs, never dump the environment, and the tests scan for committed tokens and keys.
• Verified. CI runs the test suite on Python 3.9 and 3.12, runs shellcheck on every script, and fails when generated host files drift from manifest.json.

Install

The one-liner above installs every skill. Variations:

npx skills add Alex72-py/termux-elite --list                          # see what is inside
npx skills add Alex72-py/termux-elite --skill python-native-build     # just one
npx skills add Alex72-py/termux-elite -g                              # all projects, not just this one

Inside Termux itself, npx needs Node: pkg install nodejs.

Native installs for each host:

No Node needed from a clone. The installer works on any host that reads skill directories, including inside Termux:

git clone https://github.com/Alex72-py/termux-elite.git
cd termux-elite
sh scripts/install.sh claude --dry-run    # see what would change
sh scripts/install.sh claude              # install (managed copy)
sh scripts/install.sh claude --uninstall  # remove only what it installed

It copies by default (--link symlinks), supports --project and --skill NAME, and never overwrites or removes a skill it did not install. Per-host paths and caveats are in adapters/.

FAQ

Is this a shell or a framework? No. It is a knowledge and procedure layer. The agent still owns confirmation and execution.

Does it run commands on my phone? Only the agent does, through its normal tool permissions. The bundled helper scripts are read-only and print facts.

Will it work on a normal Linux machine? It is written for Termux, Android, and proot, and says so when a fact is Android-specific. A few skills (github-actions, git-credentials) are useful anywhere, but the focus is the phone.

Can I route from my own agent? Yes. Anything that can read files can route from manifest.json. See adapters/generic.

Help it cover more failures

The most useful contribution is a real failure that no skill handled, or one where a skill gave the wrong advice. Open a failure report issue with your Android and Termux versions and the first error line (redact secrets). If the failure is a repeatable decision, it may become a new skill: see CONTRIBUTING.md for the quality bar and docs/SKILL_TEMPLATE.md to start one.

Repository layout

skills/<name>/SKILL.md         the procedure (Agent Skills frontmatter: name, description, license, compatibility, metadata)
skills/<name>/scripts/         small read-only helpers that print key: value facts
manifest.json                  discovery index (name, triggers, capabilities, risk, related, scripts)
AGENTS.md                      generated routing index and rules, for hosts that load context files
scripts/install.sh             installer for hosts that read skill directories
scripts/sync_hosts.py          generates host manifests and AGENTS.md from manifest.json
adapters/<host>/               notes for each host
docs/SKILL_TEMPLATE.md         starting point for a new skill
tests/                         manifest, frontmatter, section, handoff, script, host and installer checks

The plugin manifests (.claude-plugin/, .codex-plugin/, .cursor-plugin/, .agents/plugins/, plugin.json, gemini-extension.json) are generated; do not edit them by hand.

Develop

python -m pip install pytest pyyaml
python scripts/sync_hosts.py --check
python -m pytest -q

Design rules

1. Inspect before mutating.
2. Never assume native Termux, Android, Linux, or proot are interchangeable.
3. Treat package installs, permission changes, config edits, and service changes as mutating actions that need confirmation.
4. Never print secrets or broad environment dumps.
5. Verify the original failure after a change and record how to roll back.
6. Mark version-specific claims; keep helper scripts auditable and dependency-light.

MIT