claude-code-termux

Claude Code Termux

A community wrapper for Claude Code CLI that fixes compatibility issues on Termux (Android terminal emulator).

Features

This wrapper addresses the following issues when running Claude Code on Termux:

Issue	Status	Description
Sharp module failure	Fixed	Uses WebAssembly fallback for android-arm64
Ripgrep binary missing	Fixed	Auto-downloads or links to system ripgrep
Custom slash commands	Fixed	Normalizes paths for Termux filesystem
PostToolUse hooks	Fixed	Patches event emission for Android
OAuth token storage	Fixed	Provides encrypted file-based fallback

Requirements

• Termux from F-Droid (NOT Google Play)
• Node.js 18-24 (v25+ has compatibility issues)
• 4GB+ RAM recommended

Quick Install

Run this one-liner in Termux:

curl -fsSL https://raw.githubusercontent.com/findingjimoh/claude-cli-termux/main/scripts/setup-termux.sh | bash

Or install manually:

# Update packages
pkg update && pkg upgrade -y

# Install dependencies
pkg install nodejs git ripgrep -y

# Install Claude Code Termux
npm install -g claude-code-termux

# Install Sharp WASM for image support
npm install -g @img/sharp-wasm32 --force

Usage

API Key Authentication (Recommended)

# Set your API key
export ANTHROPIC_API_KEY=your-api-key

# Start Claude Code
claude

To persist across sessions:

echo 'export ANTHROPIC_API_KEY=your-api-key' >> ~/.bashrc

OAuth Authentication (Experimental)

claude login

Note: OAuth has known issues on Termux. API key authentication is more reliable.

Verification

Run the verification script to check your installation:

npx claude-code-termux verify
# or
node /path/to/claude-code-termux/scripts/verify-install.js

Troubleshooting

Sharp Module Error

Error: Could not load the "sharp" module using the android-arm64 runtime

Solution:

npm install -g @img/sharp-wasm32 --force
npm install -g sharp --force

Ripgrep Not Found

Error: spawn .../vendor/ripgrep/arm64-android/rg ENOENT

Solution:

pkg install ripgrep

Custom Slash Commands Not Loading

Ensure your commands are in the correct directory:

mkdir -p ~/.claude/commands
# Create your command files here

Memory/Crash Issues

If you experience crashes:

1. Ensure you have enough free RAM (4GB+ recommended)
2. Try using an older Node.js version:

   pkg install nodejs-lts

3. Set DEBUG=1 for verbose output:

   DEBUG=1 claude

Shell Not Found Error

Error: No suitable shell found

Solution:

export SHELL=/data/data/com.termux/files/usr/bin/bash

Add to ~/.bashrc for persistence.

Known Limitations

1. Image reading - Works but requires Sharp WASM installation
2. GitHub App installation - /install-github-app may not work properly
3. Some hooks - PostToolUse hooks may have issues on some devices
4. Performance - Slightly slower than desktop due to mobile hardware

How It Works

This package is a wrapper around the official @anthropic-ai/claude-code package. It:

1. Installs the official Claude Code as a dependency
2. Applies runtime patches for Termux compatibility
3. Sets up necessary binaries and configurations
4. Provides fallback mechanisms for unsupported features

This approach means you automatically get updates from the official package while maintaining Termux compatibility.

Debug Mode

Enable debug output:

DEBUG=1 claude

For hook-specific debugging:

DEBUG_HOOKS=1 claude

Contributing

Contributions are welcome! Please:

1. Fork this repository
2. Create a feature branch
3. Submit a pull request

Related Issues

• Sharp WASM Support #2248
• Custom Commands #9435
• PostToolUse Hooks #15617
• Memory Corruption #12160
• Ripgrep/Auth #6244

License

MIT License - see LICENSE for details.

Disclaimer

This is a community project and is not officially supported by Anthropic. Use at your own risk.