termux-skill

Termux API skill for AI agents — control Android devices via Termux API.

npx -y termux-skill

Installs a SKILL.md in .agents/skills/termux-api/ (and other agent directories) so your AI agent (OpenCode, Claude Code, Cursor, Copilot, etc.) can control Android via Termux API.

What it does

• Auto-detects native Termux, proot-distro, or falls back to SSH (port 8022)
• 70+ device APIs: camera, sensors, GPS, SMS, notifications, clipboard, TTS, torch, WiFi, battery
• Anti-compaction design: survives AI context compaction with persistent state
• Automatic path resolution: handles proot-distro paths automatically
• Installs to all supported agent directories automatically
• Writes skills-lock.json and updates CLAUDE.md

Usage

# Install (or update if hash changed)
npx -y termux-skill

# Force reinstall
npx termux-skill --update

# Remove skill and clean up
npx termux-skill --uninstall

# Show help
npx termux-skill --help

Installed Files

After installation, you'll have:

.agents/skills/termux-api/
├── SKILL.md              # Main skill (compact, anti-compaction)
├── termux-COMMANDS.md    # Full command reference (70+ commands)
├── termux-EXAMPLES.md    # Common usage patterns
└── termux-state.sh       # Auto-detect environment + helpers

Quick Start

# 1. Load skill (auto-detects environment)
source termux-state.sh

# 2. Use helper function (handles paths automatically)
termux_exec termux-battery-status
termux_exec termux-camera-photo -c 0 ~/photo.jpg
termux_exec termux-tts-speak "Hello"

Anti-Compaction Design

This skill survives AI context compaction:

1. State on disk — ~/.termux-skill-state persists environment detection
2. Self-contained recovery — Single source termux-state.sh restores everything
3. No context dependency — Functions work without remembering conversation history

After context compaction, recover with:

source termux-state.sh
# Output: State loaded: ENV=proot PREFIX=/data/data/com.termux/files/usr/bin

proot-distro Path Handling

⚠️ Important for proot-distro environments:

• Never use: /root/, /tmp/, /home/
• Always use: /data/data/com.termux/files/home/
• termux_exec resolves paths automatically

# This works automatically:
termux_exec termux-camera-photo -c 0 ~/photo.jpg
# Resolves to: /data/data/com.termux/files/home/photo.jpg

API Examples

| Command | Description | |---------|-------------| | termux-battery-status | Battery level, charging status | | termux-camera-photo -c 1 ~/foto.jpg | Take photo (front camera) | | termux-notification -t "Hola" -c "Mundo" | Show notification | | termux-location -p network | Get GPS location | | termux-sms-send -n +123 "message" | Send SMS | | termux-tts-speak "Hello" | Text to speech | | termux-clipboard-get | Get clipboard text | | termux-torch on | Toggle flashlight |

Documentation

• SKILL.md — Main skill instructions
• termux-COMMANDS.md — Full command reference
• termux-EXAMPLES.md — Usage examples
• termux-QUICK-REF.md — Top 15 commands