Hooks don't fire on Android/Termux - platform detection issue

Summary

All hooks (PreToolUse, PostToolUse, SessionStart, Stop, SubagentStop) fail to fire automatically on Android running in Termux. Manual hook execution works, but the internal event dispatcher never triggers them.

Environment

• Platform: Android 14 (Samsung Galaxy S24 Ultra)
• Terminal: Termux
• Node.js: v25.2.1
• Claude Code: Latest from npm
• Architecture: arm64

Root Cause Analysis

After extensive diagnosis, the root cause has been identified:

Platform Detection Mismatch

On Termux, Node.js reports:

process.platform  // "android" (NOT "linux")
os.type()         // "Linux"
process.arch      // "arm64"

Missing Android Platform Support

Searching the Claude Code CLI bundle (cli.js) reveals platform-specific checks:

platform==="darwin"   // macOS handling
platform!=="win32"    // Windows exclusion  
platform==="linux"    // Linux specific code

No code path exists for platform === "android"

This causes the event dispatcher to silently skip hook registration/triggering when running on Termux.

Evidence

Test Setup

• Configured hooks in ~/.claude/settings.json for all event types
• Hook scripts are valid TypeScript files that log to a JSONL file
• Manual execution of hooks via bash works correctly

Results

| Test | Result |
|------|--------|
| Manual hook execution | ✅ Works |
| SessionStart auto-trigger | ❌ Never fires |
| PreToolUse auto-trigger | ❌ Never fires |
| PostToolUse auto-trigger | ❌ Never fires |
| Hook script validity | ✅ Confirmed working |

Hook Configuration (working config, hooks just don't fire)

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "",
        "hooks": ["~/.claude/Tools/capture-all-events.ts"]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "",
        "hooks": ["~/.claude/Tools/capture-all-events.ts"]
      }
    ]
  }
}

Suggested Fix

Add "android" to the list of recognized platforms, treating it similarly to "linux" since Termux provides a Linux-like environment:

// Pseudocode for the fix
if (platform === "linux" || platform === "android") {
  // Enable hooks and Linux-compatible features
}

Related Issues

• #15617 - Reports PostToolUse hooks not firing (may be same root cause)
• Community repo documenting Termux issues: https://github.com/eduterre/claude-code-termux

Additional Context

Other Termux-specific issues that have been resolved:

• Sharp/image reading: Fixed with @img/sharp-wasm32 WASM fallback
• Custom slash commands: Working (contrary to some reports)
• Custom subagents: Working (contrary to some reports)

The hook system is the last major blocker for full Claude Code functionality on Android/Termux.

---
This issue was composed by Claude (AI Assistant) based on hands-on diagnosis in a Termux environment.