claude-code-termux 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Claude Code Termux Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,198 @@
+# Claude Code Termux
+
+A community wrapper for [Claude Code CLI](https://github.com/anthropics/claude-code) 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](https://f-droid.org/en/packages/com.termux/) (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
+
+### API Key Authentication (Recommended)
+
+```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
+```
+
+### OAuth Authentication (Experimental)
+
+```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
+
+### Sharp Module Error
+
+```
+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
+```
+
+### Ripgrep Not Found
+
+```
+Error: spawn .../vendor/ripgrep/arm64-android/rg ENOENT
+```
+
+**Solution:**
+```bash
+pkg install ripgrep
+```
+
+### Custom Slash Commands Not Loading
+
+Ensure your commands are in the correct directory:
+
+```bash
+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:
+   ```bash
+   pkg install nodejs-lts
+   ```
+3. Set DEBUG=1 for verbose output:
+   ```bash
+   DEBUG=1 claude
+   ```
+
+### Shell Not Found Error
+
+```
+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](https://github.com/anthropics/claude-code/issues/2248)
+- [Custom Commands #9435](https://github.com/anthropics/claude-code/issues/9435)
+- [PostToolUse Hooks #15617](https://github.com/anthropics/claude-code/issues/15617)
+- [Memory Corruption #12160](https://github.com/anthropics/claude-code/issues/12160)
+- [Ripgrep/Auth #6244](https://github.com/anthropics/claude-code/issues/6244)
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Disclaimer
+
+This is a community project and is not officially supported by Anthropic. Use at your own risk.

package/bin/claude-termux.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+
+/**
+ * Claude Code Termux Wrapper
+ *
+ * This wrapper applies Termux/Android-specific patches before loading
+ * the official Claude Code CLI. It fixes issues with:
+ * - Sharp module (uses WASM fallback on android-arm64)
+ * - Ripgrep binary (ensures ARM64 binary is available)
+ * - Path resolution (handles Termux's non-standard paths)
+ * - OAuth token storage (provides fallback when keychain unavailable)
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+
+// Detect if running on Termux/Android
+const isTermux = process.platform === 'android' ||
+                 process.env.PREFIX?.includes('com.termux') ||
+                 process.env.HOME?.includes('com.termux');
+
+// Apply runtime patches for Termux
+if (isTermux) {
+  console.log('[claude-code-termux] Detected Termux environment, applying patches...');
+
+  try {
+    // Apply all patches
+    require('../src/patches/apply-all');
+  } catch (err) {
+    console.error('[claude-code-termux] Warning: Some patches could not be applied:', err.message);
+  }
+}
+
+// Find the Claude Code CLI entry point
+let claudeCodePath;
+try {
+  // Try to resolve the claude-code package
+  claudeCodePath = require.resolve('@anthropic-ai/claude-code/cli.mjs');
+} catch (err) {
+  // Fallback: look in node_modules
+  const possiblePaths = [
+    path.join(__dirname, '..', 'node_modules', '@anthropic-ai', 'claude-code', 'cli.mjs'),
+    path.join(__dirname, '..', '..', '@anthropic-ai', 'claude-code', 'cli.mjs'),
+    path.join(process.env.PREFIX || '/usr', 'lib', 'node_modules', '@anthropic-ai', 'claude-code', 'cli.mjs'),
+  ];
+
+  for (const p of possiblePaths) {
+    if (fs.existsSync(p)) {
+      claudeCodePath = p;
+      break;
+    }
+  }
+
+  if (!claudeCodePath) {
+    console.error('[claude-code-termux] Error: Could not find @anthropic-ai/claude-code');
+    console.error('Please ensure it is installed: npm install @anthropic-ai/claude-code');
+    process.exit(1);
+  }
+}
+
+// Import and run Claude Code
+// Use dynamic import since cli.mjs is an ES module
+import(claudeCodePath).catch(err => {
+  console.error('[claude-code-termux] Error loading Claude Code:', err.message);
+
+  if (err.message.includes('sharp')) {
+    console.error('\nSharp module error detected. Try running:');
+    console.error('  npm install @img/sharp-wasm32 --force');
+    console.error('  npm install sharp --force');
+  }
+
+  if (err.message.includes('ENOENT') && err.message.includes('ripgrep')) {
+    console.error('\nRipgrep binary not found. Try running:');
+    console.error('  pkg install ripgrep');
+  }
+
+  process.exit(1);
+});

package/docs/INSTALLATION.md

@@ -0,0 +1,136 @@
+# Installation Guide
+
+This guide provides detailed installation instructions for Claude Code on Termux.
+
+## Prerequisites
+
+### 1. Install Termux
+
+**Important:** Install Termux from [F-Droid](https://f-droid.org/en/packages/com.termux/), NOT the Google Play Store. The Play Store version is outdated and may not work properly.
+
+1. Download F-Droid from https://f-droid.org/
+2. Search for "Termux" in F-Droid
+3. Install Termux
+
+### 2. Grant Storage Permission
+
+After installing Termux, run:
+
+```bash
+termux-setup-storage
+```
+
+This allows Termux to access your device storage.
+
+## Installation Methods
+
+### Method 1: One-Line Install (Recommended)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/findingjimoh/claude-cli-termux/main/scripts/setup-termux.sh | bash
+```
+
+### Method 2: Manual Installation
+
+#### Step 1: Update Packages
+
+```bash
+pkg update && pkg upgrade -y
+```
+
+#### Step 2: Install Node.js
+
+```bash
+pkg install nodejs -y
+```
+
+Verify the version:
+
+```bash
+node --version
+```
+
+You need Node.js 18-24. If you have v25+, install the LTS version:
+
+```bash
+pkg install nodejs-lts -y
+```
+
+#### Step 3: Install Git
+
+```bash
+pkg install git -y
+```
+
+#### Step 4: Install Ripgrep
+
+```bash
+pkg install ripgrep -y
+```
+
+Verify it works:
+
+```bash
+rg --version
+```
+
+#### Step 5: Install Claude Code Termux
+
+```bash
+npm install -g claude-code-termux
+```
+
+#### Step 6: Install Sharp WASM (for image support)
+
+```bash
+npm install -g @img/sharp-wasm32 --force
+```
+
+## Post-Installation Setup
+
+### Set API Key
+
+Get your API key from https://console.anthropic.com/
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-api03-...
+```
+
+To make it persistent:
+
+```bash
+echo 'export ANTHROPIC_API_KEY=sk-ant-api03-...' >> ~/.bashrc
+source ~/.bashrc
+```
+
+### Verify Installation
+
+```bash
+node $(npm root -g)/claude-code-termux/scripts/verify-install.js
+```
+
+### Start Claude Code
+
+```bash
+claude
+```
+
+## Updating
+
+To update to the latest version:
+
+```bash
+npm update -g claude-code-termux
+```
+
+## Uninstalling
+
+```bash
+npm uninstall -g claude-code-termux
+npm uninstall -g @anthropic-ai/claude-code
+```
+
+## Next Steps
+
+- Read the [Troubleshooting Guide](TROUBLESHOOTING.md) if you encounter issues
+- Check [Known Issues](KNOWN-ISSUES.md) for current limitations

package/docs/KNOWN-ISSUES.md

@@ -0,0 +1,135 @@
+# Known Issues
+
+This document tracks known issues and limitations when running Claude Code on Termux.
+
+## Current Status
+
+| Feature | Status | Notes |
+|---------|--------|-------|
+| Basic CLI | Working | Core functionality works |
+| Bash commands | Working | File and git operations work |
+| Code search (ripgrep) | Working | Requires `pkg install ripgrep` |
+| Image reading | Partial | Requires Sharp WASM installation |
+| Custom slash commands | Partial | May require manual setup |
+| Hooks (Pre/Post) | Partial | PostToolUse has issues |
+| OAuth login | Experimental | API key recommended |
+| MCP support | Working | Model Context Protocol works |
+
+## Open Issues
+
+### 1. PostToolUse Hooks Not Firing
+
+**Issue:** [#15617](https://github.com/anthropics/claude-code/issues/15617)
+
+PostToolUse hooks don't trigger on Termux/Android, while other hook types work correctly.
+
+**Status:** Partially mitigated with event patching
+
+**Workaround:** Use PreToolUse hooks where possible
+
+---
+
+### 2. Custom Slash Commands Not Loading
+
+**Issue:** [#9435](https://github.com/anthropics/claude-code/issues/9435)
+
+Custom slash commands in `.claude/commands/` are not discovered on Termux.
+
+**Status:** Partially mitigated with path normalization
+
+**Workaround:** Ensure correct permissions and absolute paths
+
+---
+
+### 3. Image Reading Requires Extra Setup
+
+**Issue:** [#2248](https://github.com/anthropics/claude-code/issues/2248)
+
+Sharp module fails to load on android-arm64.
+
+**Status:** Fixed with WASM fallback
+
+**Solution:** `npm install @img/sharp-wasm32 --force`
+
+---
+
+### 4. GitHub App Installation Stuck
+
+**Issue:** [#3585](https://github.com/anthropics/claude-code/issues/3585)
+
+`/install-github-app` command doesn't progress past organization input.
+
+**Status:** Not fixed
+
+**Workaround:** Use GitHub CLI (`gh`) directly or configure on desktop
+
+---
+
+### 5. Memory Corruption on Some Devices
+
+**Issue:** [#12160](https://github.com/anthropics/claude-code/issues/12160)
+
+"double free or corruption" crash on ARM64.
+
+**Status:** Partially mitigated
+
+**Workaround:**
+- Use Node.js v24.11.1+
+- Use older Claude Code version (0.2.114)
+
+---
+
+### 6. OAuth Token Persistence
+
+**Issue:** [#6244](https://github.com/anthropics/claude-code/issues/6244)
+
+OAuth tokens don't persist across sessions.
+
+**Status:** Partially mitigated with file-based storage
+
+**Workaround:** Use API key authentication
+
+---
+
+### 7. Node.js v25+ Incompatibility
+
+Node.js v25+ removed the SlowBuffer API that Claude Code depends on.
+
+**Status:** Known issue
+
+**Workaround:** Use Node.js 18-24
+
+---
+
+## Feature Limitations
+
+### Compared to Desktop
+
+1. **Performance** - Slower due to mobile hardware
+2. **Memory** - Limited by device RAM
+3. **IDE integration** - Not applicable on mobile
+4. **GUI features** - No visual diff, no browser integration
+
+### Termux-Specific
+
+1. **Storage access** - Requires `termux-setup-storage`
+2. **Background execution** - May be killed by Android
+3. **Notifications** - Limited notification support
+4. **Clipboard** - Requires Termux:API addon
+
+## Reporting New Issues
+
+When reporting issues, include:
+
+```
+Termux version: (from pkg list-installed termux-\*)
+Node.js version: (node --version)
+Claude Code version: (npm list -g @anthropic-ai/claude-code)
+Android version: (getprop ro.build.version.release)
+Device: (getprop ro.product.model)
+Architecture: (uname -m)
+```
+
+File issues at:
+- **Termux-specific:** This repository
+- **General Claude Code:** [anthropics/claude-code](https://github.com/anthropics/claude-code/issues)