Termux Runner

A skill that standardizes the process of running commands inside the Termux app (not directly via root shell), suitable for long tasks such as pkg update, npm install, bootstrap/update scripts.

Scope

• In-scope: control the Termux app via RunCommandService, monitor long-running logs, collect exit codes, handle install/update errors on Android.
• Out-of-scope: generic adb/am automation outside the Termux runner contract.

Indexed sub-skill references (source map)

• @[SKILL.md#L1-L136] Standard frontmatter (name, description).
• @[SKILL.md#L6-L136] Termux Runner.
• @[SKILL.md#L10-L136] Indexed sub-skill references.
• @[SKILL.md#L22-L136] When to use.
• @[SKILL.md#L27-L136] Mandatory principles.
• @[SKILL.md#L39-L136] Standard paths.
• @[SKILL.md#L44-L136] Standard flow (long-running).
• @[SKILL.md#L56-L136] Minimal template.
• @[SKILL.md#L79-L136] Start RunCommandService.
• @[SKILL.md#L88-L136] Common errors + how to handle them.
• @[SKILL.md#L109-L136] Job completion checklist.

When to use

• Need to execute commands in the context of the com.termux app.
• Need to monitor long-running progress + get logs + clear exit codes.
• Need to debug installation errors in Termux without polluting the main runtime.

Mandatory principles

1. Do not run pkg/apt directly via root shell (Termux will block it or the context will be wrong).
2. Always run through com.termux/.app.RunCommandService.
3. Before running an external command, ensure:
   • ~/.termux/termux.properties contains allow-external-apps=true.
4. Every long-running job must have:
   • a log file (*.log),
   • an exit code file (*.exit),
   • a dedicated runner script (*.sh).
5. The runner script must use an absolute shebang:
   • #!/data/data/com.termux/files/usr/bin/bash

Standard paths

• TERMUX_HOME=/data/data/com.termux/files/home
• PREFIX=/data/data/com.termux/files/usr
• PATH=$PREFIX/bin:$PATH

Standard flow (long-running)

1. Create a runner script in TERMUX_HOME.
2. In the runner:
   • set env PREFIX, PATH
   • run the command
   • redirect output to the log
   • write the exit code to a .exit file
3. Start service:
   • am startservice -n com.termux/.app.RunCommandService -a com.termux.RUN_COMMAND ...
4. Poll the .exit file with a reasonable timeout.
5. Return the result with log tail + exit code.

Minimal template

#!/data/data/com.termux/files/usr/bin/bash
set -o pipefail
export PREFIX=/data/data/com.termux/files/usr
export PATH="$PREFIX/bin:$PATH"
cd /data/data/com.termux/files/home || exit 98

LOG="/data/data/com.termux/files/home/job.log"
EXITF="/data/data/com.termux/files/home/job.exit"
rm -f "$EXITF"

{
  echo "== [$(date)] start =="
  # command here
  echo "== [$(date)] done =="
} > "$LOG" 2>&1

code=$?
printf "%s\n" "$code" > "$EXITF"
exit "$code"

Start RunCommandService

am startservice -n com.termux/.app.RunCommandService \
  -a com.termux.RUN_COMMAND \
  --es com.termux.RUN_COMMAND_PATH /data/data/com.termux/files/home/<runner>.sh \
  --ez com.termux.RUN_COMMAND_BACKGROUND true \
  --es com.termux.RUN_COMMAND_WORKDIR /data/data/com.termux/files/home

Common errors + how to handle them

1) Cannot run 'pkg' command as root

• Cause: running in the wrong context (root shell instead of Termux app).
• Fix: run via RunCommandService.

2) bad interpreter: /usr/bin/env

• Cause: script shebang like /usr/bin/env node does not fit the Android/Termux path.
• Fix: create a wrapper with the absolute path to node in $PREFIX/bin.

3) Script reports "Update Complete" but runtime is still broken

• Cause: the installer skipped some native dependency errors (non-critical warning).
• Fix: always verify after execution with:
  • command -v openclaw
  • openclaw --version
• Only consider it successful when verification passes.

4) Native deps (e.g. koffi, @discordjs/opus, sharp) fail to build

• Collect the full npm log (~/.npm/_logs/...) and job log.
• Do not conclude success if runtime errors still remain.

Job completion checklist

• Exit file is present
• Exit code is clear
• Log tail has enough error/success context
• Main verify command runs successfully (e.g. openclaw --version)
• If failed: return root cause + next fix step

Trigger Rules

• Positive: Activate when the user request matches termux-runner by description: Control the Termux app (com.termux) to run commands safely through RunCommandService, monitor long-running logs, collect exit codes, and handle install/update errors in the Android environment.
• Negative: Do not activate for out-of-scope requests or when this skill's workflow/expertise is not needed.
• Escalation: If there is external action/network write or sensitive operations, an approval checkpoint must be added before execution.

Output Contract

• Deliverable: a result aligned with the objective of termux-runner; clearly state the artifact/path/steps performed (if any).
• Validation: report PASS/FAIL status together with the main checks run.
• Failure mode: when there is an error, state the root cause + proposed remediation.

SOP

1. Determine whether the request is within the scope of the skill.
2. Execute the skill's main workflow/instructions in safe order.
3. Check results, state validation, and next steps.

Error Handling

• If input/permissions are missing: state clearly what is missing and request it.
• If there is a runtime/tool error: return a brief error + possible cause + proposed remediation.
• If there is a policy/safety risk: stop and escalate via the approval checkpoint.