claude-code-termux 1.0.0

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,225 @@
+# Troubleshooting Guide
+
+This guide helps you resolve common issues with Claude Code on Termux.
+
+## Common Issues
+
+### 1. Sharp Module Error
+
+**Error:**
+```
+Error: Could not load the "sharp" module using the android-arm64 runtime
+```
+
+**Cause:** The Sharp image library doesn't have native binaries for Android ARM64.
+
+**Solution:**
+```bash
+npm install -g @img/sharp-wasm32 --force
+npm install -g sharp --force
+```
+
+The `--force` flag is needed to override the native binary with the WebAssembly version.
+
+---
+
+### 2. Ripgrep Binary Not Found
+
+**Error:**
+```
+Error: spawn /data/data/com.termux/files/usr/lib/node_modules/@anthropic-ai/claude-code/vendor/ripgrep/arm64-android/rg ENOENT
+```
+
+**Cause:** Claude Code ships with platform-specific ripgrep binaries, but android-arm64 isn't included.
+
+**Solution:**
+```bash
+pkg install ripgrep
+```
+
+The wrapper will automatically use the system ripgrep.
+
+---
+
+### 3. Shell Not Found
+
+**Error:**
+```
+Command failed: No suitable shell found. Claude CLI requires a Posix shell environment.
+```
+
+**Cause:** Claude Code has an allowlist of shell paths that doesn't include Termux's location.
+
+**Solution:**
+```bash
+export SHELL=/data/data/com.termux/files/usr/bin/bash
+```
+
+Add to ~/.bashrc for persistence:
+```bash
+echo 'export SHELL=/data/data/com.termux/files/usr/bin/bash' >> ~/.bashrc
+```
+
+---
+
+### 4. Memory Crash / Double Free
+
+**Error:**
+```
+double free or corruption (out)
+Aborted
+```
+
+**Cause:** Native binaries compiled for x86_64 running on ARM64, or Node.js version issues.
+
+**Solutions:**
+
+1. Upgrade Node.js:
+   ```bash
+   pkg install nodejs-lts
+   ```
+
+2. Use an older Claude Code version:
+   ```bash
+   npm install -g @anthropic-ai/claude-code@0.2.114
+   ```
+
+3. Ensure you have enough free memory (4GB+ recommended)
+
+---
+
+### 5. OAuth Login Stuck
+
+**Problem:** OAuth login appears to succeed but subsequent commands fail with authentication errors.
+
+**Cause:** Token persistence issues with the system keychain on Android.
+
+**Solution:** Use API key authentication instead:
+```bash
+export ANTHROPIC_API_KEY=your-api-key
+```
+
+---
+
+### 6. Custom Commands Not Loading
+
+**Problem:** Commands in `~/.claude/commands/` are not discovered.
+
+**Cause:** Path resolution issues with Termux's non-standard directory structure.
+
+**Solution:**
+
+1. Ensure the directory exists:
+   ```bash
+   mkdir -p ~/.claude/commands
+   ```
+
+2. Create a test command:
+   ```bash
+   cat > ~/.claude/commands/test.md << 'EOF'
+   # Test Command
+   Just respond with "Test command works!"
+   EOF
+   ```
+
+3. Set correct permissions:
+   ```bash
+   chmod 755 ~/.claude ~/.claude/commands
+   chmod 644 ~/.claude/commands/*.md
+   ```
+
+4. Restart Claude Code
+
+---
+
+### 7. Hooks Not Firing
+
+**Problem:** PostToolUse hooks don't trigger, while other hooks work.
+
+**Cause:** Event emission timing issues on Android.
+
+**Solution:**
+
+1. Enable hook debugging:
+   ```bash
+   DEBUG_HOOKS=1 claude
+   ```
+
+2. Ensure your hook scripts are executable
+3. Use absolute paths in hook commands
+
+---
+
+### 8. Slow Performance
+
+**Cause:** Mobile hardware limitations.
+
+**Solutions:**
+
+1. Close other apps to free memory
+2. Use simpler prompts
+3. Limit concurrent operations
+4. Consider using SSH to a remote machine instead
+
+---
+
+### 9. npm Install Fails
+
+**Error:** Various npm errors during installation.
+
+**Solutions:**
+
+1. Clear npm cache:
+   ```bash
+   npm cache clean --force
+   ```
+
+2. Remove node_modules and reinstall:
+   ```bash
+   rm -rf $(npm root -g)/claude-code-termux
+   npm install -g claude-code-termux
+   ```
+
+3. Check disk space:
+   ```bash
+   df -h
+   ```
+
+---
+
+### 10. "Command not found: claude"
+
+**Cause:** npm global bin directory not in PATH.
+
+**Solution:**
+```bash
+export PATH=$PATH:$(npm config get prefix)/bin
+```
+
+Add to ~/.bashrc for persistence.
+
+## Debug Mode
+
+Enable verbose output for troubleshooting:
+
+```bash
+DEBUG=1 claude
+```
+
+For hook-specific debugging:
+
+```bash
+DEBUG_HOOKS=1 claude
+```
+
+## Getting Help
+
+1. Check [Known Issues](KNOWN-ISSUES.md)
+2. Search [GitHub Issues](https://github.com/anthropics/claude-code/issues)
+3. Report new issues with:
+   - Termux version
+   - Node.js version
+   - Android version
+   - Device model
+   - Error messages
+   - Steps to reproduce

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "claude-code-termux",
+  "version": "1.0.0",
+  "description": "Claude Code CLI with Termux/Android compatibility fixes - a wrapper that patches issues with Sharp, ripgrep, and path resolution on ARM64 Android",
+  "author": "Jimoh Ovbiagele <findingjimoh@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/findingjimoh/claude-cli-termux.git"
+  },
+  "keywords": [
+    "claude",
+    "anthropic",
+    "ai",
+    "cli",
+    "termux",
+    "android",
+    "arm64",
+    "coding-assistant"
+  ],
+  "bin": {
+    "claude": "./bin/claude-termux.js",
+    "claude-termux": "./bin/claude-termux.js"
+  },
+  "main": "./bin/claude-termux.js",
+  "scripts": {
+    "postinstall": "node postinstall.js",
+    "test": "node scripts/verify-install.js"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-code": "^2.1.3"
+  },
+  "optionalDependencies": {
+    "@img/sharp-wasm32": "^0.33.5"
+  },
+  "engines": {
+    "node": ">=18.0.0 <25.0.0"
+  },
+  "os": [
+    "android",
+    "linux",
+    "darwin",
+    "win32"
+  ],
+  "cpu": [
+    "arm64",
+    "x64",
+    "arm"
+  ]
+}

package/postinstall.js

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+
+/**
+ * Claude Code Termux - Post-install Script
+ *
+ * This script runs after npm install to:
+ * 1. Detect if running on Termux/Android
+ * 2. Set up ripgrep binary for ARM64 Android
+ * 3. Ensure Sharp WASM fallback is configured
+ * 4. Create necessary directories and symlinks
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+// Detect Termux environment
+const isTermux = process.platform === 'android' ||
+                 process.env.PREFIX?.includes('com.termux') ||
+                 process.env.HOME?.includes('com.termux');
+
+const isARM64 = process.arch === 'arm64';
+
+console.log('[claude-code-termux] Post-install script running...');
+console.log(`[claude-code-termux] Platform: ${process.platform}, Arch: ${process.arch}`);
+console.log(`[claude-code-termux] Termux detected: ${isTermux}`);
+
+/**
+ * Find the Claude Code installation directory
+ */
+function findClaudeCodePath() {
+  const possiblePaths = [
+    path.join(__dirname, 'node_modules', '@anthropic-ai', 'claude-code'),
+    path.join(__dirname, '..', '@anthropic-ai', 'claude-code'),
+    path.join(process.env.PREFIX || '/usr', 'lib', 'node_modules', '@anthropic-ai', 'claude-code'),
+  ];
+
+  for (const p of possiblePaths) {
+    if (fs.existsSync(p)) {
+      return p;
+    }
+  }
+  return null;
+}
+
+/**
+ * Set up ripgrep for ARM64 Android
+ */
+function setupRipgrep(claudeCodePath) {
+  if (!isTermux || !isARM64) {
+    console.log('[claude-code-termux] Skipping ripgrep setup (not Termux ARM64)');
+    return;
+  }
+
+  console.log('[claude-code-termux] Setting up ripgrep for ARM64 Android...');
+
+  const vendorDir = path.join(claudeCodePath, 'vendor', 'ripgrep', 'arm64-android');
+
+  // Create directory if it doesn't exist
+  if (!fs.existsSync(vendorDir)) {
+    fs.mkdirSync(vendorDir, { recursive: true });
+  }
+
+  const targetBinary = path.join(vendorDir, 'rg');
+
+  // Check if we have a bundled binary
+  const bundledBinary = path.join(__dirname, 'src', 'binaries', 'rg');
+  if (fs.existsSync(bundledBinary)) {
+    console.log('[claude-code-termux] Using bundled ripgrep binary');
+    fs.copyFileSync(bundledBinary, targetBinary);
+    fs.chmodSync(targetBinary, 0o755);
+    console.log('[claude-code-termux] Ripgrep binary installed successfully');
+    return;
+  }
+
+  // Try to use system ripgrep from Termux
+  try {
+    const systemRg = execSync('which rg', { encoding: 'utf8' }).trim();
+    if (systemRg && fs.existsSync(systemRg)) {
+      console.log(`[claude-code-termux] Found system ripgrep at ${systemRg}`);
+      // Create symlink to system ripgrep
+      if (fs.existsSync(targetBinary)) {
+        fs.unlinkSync(targetBinary);
+      }
+      fs.symlinkSync(systemRg, targetBinary);
+      console.log('[claude-code-termux] Linked to system ripgrep');
+      return;
+    }
+  } catch (err) {
+    // System ripgrep not found
+  }
+
+  // Try to download ripgrep
+  console.log('[claude-code-termux] Attempting to download ripgrep...');
+  try {
+    // Use curl to download (available in Termux)
+    const rgUrl = 'https://github.com/BurntSushi/ripgrep/releases/download/14.1.1/ripgrep-14.1.1-aarch64-unknown-linux-gnu.tar.gz';
+    const tmpDir = path.join(__dirname, 'tmp');
+    const tarFile = path.join(tmpDir, 'ripgrep.tar.gz');
+
+    if (!fs.existsSync(tmpDir)) {
+      fs.mkdirSync(tmpDir, { recursive: true });
+    }
+
+    execSync(`curl -sL "${rgUrl}" -o "${tarFile}"`, { stdio: 'inherit' });
+    execSync(`tar -xzf "${tarFile}" -C "${tmpDir}"`, { stdio: 'inherit' });
+
+    // Find the rg binary in extracted files
+    const extractedDir = fs.readdirSync(tmpDir).find(f => f.startsWith('ripgrep-'));
+    if (extractedDir) {
+      const extractedBinary = path.join(tmpDir, extractedDir, 'rg');
+      if (fs.existsSync(extractedBinary)) {
+        fs.copyFileSync(extractedBinary, targetBinary);
+        fs.chmodSync(targetBinary, 0o755);
+        console.log('[claude-code-termux] Ripgrep downloaded and installed successfully');
+      }
+    }
+
+    // Cleanup
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  } catch (err) {
+    console.error('[claude-code-termux] Failed to download ripgrep:', err.message);
+    console.log('[claude-code-termux] Please install ripgrep manually: pkg install ripgrep');
+  }
+}
+
+/**
+ * Try to copy linux-arm64 binaries as android-arm64 fallback
+ */
+function copyLinuxBinariesAsAndroidFallback(claudeCodePath) {
+  if (!isTermux || !isARM64) {
+    return;
+  }
+
+  const vendorDir = path.join(claudeCodePath, 'vendor');
+  if (!fs.existsSync(vendorDir)) {
+    return;
+  }
+
+  // List of tools that might have platform-specific binaries
+  const tools = ['ripgrep'];
+
+  for (const tool of tools) {
+    const linuxPath = path.join(vendorDir, tool, 'arm64-linux');
+    const androidPath = path.join(vendorDir, tool, 'arm64-android');
+
+    if (fs.existsSync(linuxPath) && !fs.existsSync(androidPath)) {
+      console.log(`[claude-code-termux] Copying ${tool} linux-arm64 as android-arm64 fallback`);
+      try {
+        fs.cpSync(linuxPath, androidPath, { recursive: true });
+      } catch (err) {
+        console.error(`[claude-code-termux] Failed to copy ${tool}:`, err.message);
+      }
+    }
+  }
+}
+
+/**
+ * Create OAuth token storage directory
+ */
+function setupOAuthStorage() {
+  const homeDir = process.env.HOME || '/data/data/com.termux/files/home';
+  const claudeDir = path.join(homeDir, '.claude');
+
+  if (!fs.existsSync(claudeDir)) {
+    fs.mkdirSync(claudeDir, { recursive: true, mode: 0o700 });
+    console.log('[claude-code-termux] Created .claude directory');
+  }
+}
+
+/**
+ * Main setup function
+ */
+function main() {
+  const claudeCodePath = findClaudeCodePath();
+
+  if (!claudeCodePath) {
+    console.log('[claude-code-termux] Claude Code not found yet (will be installed next)');
+    return;
+  }
+
+  console.log(`[claude-code-termux] Found Claude Code at: ${claudeCodePath}`);
+
+  // Run setup tasks
+  if (isTermux) {
+    setupRipgrep(claudeCodePath);
+    copyLinuxBinariesAsAndroidFallback(claudeCodePath);
+    setupOAuthStorage();
+  }
+
+  console.log('[claude-code-termux] Post-install complete!');
+
+  if (isTermux) {
+    console.log('\n[claude-code-termux] Termux setup tips:');
+    console.log('  - If you encounter Sharp errors, run: npm install @img/sharp-wasm32 --force');
+    console.log('  - If you encounter ripgrep errors, run: pkg install ripgrep');
+    console.log('  - Use API key auth: export ANTHROPIC_API_KEY=your-key');
+    console.log('\nRun "claude" to start Claude Code!');
+  }
+}
+
+main();

package/scripts/download-ripgrep.sh

@@ -0,0 +1,55 @@
+#!/bin/bash
+
+# Download ripgrep for ARM64 Linux (works on Termux)
+# This script downloads and extracts the ripgrep binary
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
+BINARIES_DIR="$PROJECT_DIR/src/binaries"
+
+# Ripgrep version and URL
+RG_VERSION="14.1.1"
+RG_URL="https://github.com/BurntSushi/ripgrep/releases/download/${RG_VERSION}/ripgrep-${RG_VERSION}-aarch64-unknown-linux-gnu.tar.gz"
+
+echo "Downloading ripgrep v${RG_VERSION} for ARM64..."
+
+# Create binaries directory
+mkdir -p "$BINARIES_DIR"
+
+# Create temp directory
+TMP_DIR=$(mktemp -d)
+trap "rm -rf $TMP_DIR" EXIT
+
+# Download
+curl -sL "$RG_URL" -o "$TMP_DIR/ripgrep.tar.gz"
+
+# Extract
+tar -xzf "$TMP_DIR/ripgrep.tar.gz" -C "$TMP_DIR"
+
+# Find and copy the binary
+RG_BINARY=$(find "$TMP_DIR" -name "rg" -type f | head -1)
+
+if [[ -z "$RG_BINARY" ]]; then
+    echo "Error: ripgrep binary not found in archive"
+    exit 1
+fi
+
+cp "$RG_BINARY" "$BINARIES_DIR/rg"
+chmod +x "$BINARIES_DIR/rg"
+
+echo "Ripgrep binary saved to: $BINARIES_DIR/rg"
+echo ""
+
+# Verify
+if [[ -x "$BINARIES_DIR/rg" ]]; then
+    echo "Verification:"
+    file "$BINARIES_DIR/rg"
+    ls -la "$BINARIES_DIR/rg"
+    echo ""
+    echo "Success! Ripgrep binary is ready."
+else
+    echo "Error: Binary verification failed"
+    exit 1
+fi

package/scripts/setup-termux.sh

@@ -0,0 +1,120 @@
+#!/bin/bash
+
+# Claude Code Termux Setup Script
+# This script sets up Claude Code with Termux compatibility fixes
+
+set -e
+
+echo "========================================"
+echo "  Claude Code Termux Setup"
+echo "========================================"
+echo ""
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Check if running in Termux
+if [[ -z "$PREFIX" ]] || [[ ! "$PREFIX" == *"com.termux"* ]]; then
+    echo -e "${YELLOW}Warning: This script is designed for Termux on Android${NC}"
+    echo "Current PREFIX: $PREFIX"
+    read -p "Continue anyway? (y/N) " -n 1 -r
+    echo
+    if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+        exit 1
+    fi
+fi
+
+# Step 1: Update packages
+echo -e "${GREEN}[1/6]${NC} Updating Termux packages..."
+pkg update -y && pkg upgrade -y
+
+# Step 2: Install Node.js
+echo -e "${GREEN}[2/6]${NC} Installing Node.js..."
+if command -v node &> /dev/null; then
+    NODE_VERSION=$(node --version)
+    echo "Node.js already installed: $NODE_VERSION"
+else
+    pkg install nodejs -y
+fi
+
+# Check Node.js version
+NODE_MAJOR=$(node --version | cut -d'.' -f1 | tr -d 'v')
+if [[ "$NODE_MAJOR" -lt 18 ]]; then
+    echo -e "${RED}Error: Node.js 18+ required, found v$NODE_MAJOR${NC}"
+    exit 1
+fi
+
+if [[ "$NODE_MAJOR" -ge 25 ]]; then
+    echo -e "${YELLOW}Warning: Node.js 25+ may have compatibility issues${NC}"
+    echo "Consider installing Node.js 24: pkg install nodejs-lts"
+fi
+
+# Step 3: Install git
+echo -e "${GREEN}[3/6]${NC} Installing git..."
+if command -v git &> /dev/null; then
+    echo "Git already installed"
+else
+    pkg install git -y
+fi
+
+# Step 4: Install ripgrep
+echo -e "${GREEN}[4/6]${NC} Installing ripgrep..."
+if command -v rg &> /dev/null; then
+    echo "Ripgrep already installed"
+else
+    pkg install ripgrep -y
+fi
+
+# Step 5: Install Claude Code Termux
+echo -e "${GREEN}[5/6]${NC} Installing Claude Code Termux..."
+
+# Check if already installed
+if npm list -g claude-code-termux &> /dev/null; then
+    echo "Updating existing installation..."
+    npm update -g claude-code-termux
+else
+    npm install -g claude-code-termux
+fi
+
+# Also install Sharp WASM for image support
+echo "Installing Sharp WASM for image support..."
+npm install -g @img/sharp-wasm32 --force 2>/dev/null || true
+
+# Step 6: Verify installation
+echo -e "${GREEN}[6/6]${NC} Verifying installation..."
+
+if command -v claude &> /dev/null; then
+    echo -e "${GREEN}Claude Code Termux installed successfully!${NC}"
+else
+    echo -e "${YELLOW}Warning: 'claude' command not found in PATH${NC}"
+    echo "You may need to restart your terminal or add npm global bin to PATH:"
+    echo "  export PATH=\$PATH:\$(npm config get prefix)/bin"
+fi
+
+echo ""
+echo "========================================"
+echo "  Setup Complete!"
+echo "========================================"
+echo ""
+echo "Next steps:"
+echo ""
+echo "1. Set your API key:"
+echo "   export ANTHROPIC_API_KEY=your-api-key"
+echo ""
+echo "2. Add to .bashrc for persistence:"
+echo "   echo 'export ANTHROPIC_API_KEY=your-key' >> ~/.bashrc"
+echo ""
+echo "3. Start Claude Code:"
+echo "   claude"
+echo ""
+echo "For OAuth login (experimental):"
+echo "   claude login"
+echo ""
+echo "Troubleshooting:"
+echo "- If you get Sharp errors: npm install @img/sharp-wasm32 --force"
+echo "- If you get ripgrep errors: pkg install ripgrep"
+echo "- Set DEBUG=1 for verbose output"
+echo ""