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:

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

Or install manually:

`bash


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

$3

`bash


Set your API key

export ANTHROPIC_API_KEY=your-api-key

Start Claude Code

claude
`

To persist across sessions:

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

$3

`bash
claude login
`

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

Verification

Run the verification script to check your installation:

`bash
npx claude-code-termux verify


or


node /path/to/claude-code-termux/scripts/verify-install.js
`

Troubleshooting

$3

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

Solution:
`bash
npm install -g @img/sharp-wasm32 --force
npm install -g sharp --force
`

$3

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

Solution:
`bash
pkg install ripgrep
`

$3

Ensure your commands are in the correct directory:

`bash
mkdir -p ~/.claude/commands


Create your command files here


`

$3

If you experience crashes:

1. Ensure you have enough free RAM (4GB+ recommended)
2. Try using an older Node.js version:
`bash
pkg install nodejs-lts
`
3. Set DEBUG=1 for verbose output:
`bash
DEBUG=1 claude
`

$3

`
Error: No suitable shell found
`

Solution:
`bash
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:

`bash
DEBUG=1 claude
`

For hook-specific debugging:

`bash
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.