claude-code-termux/README.md

# Claude Code for Termux

Run [Claude Code](https://claude.ai/code) CLI on Android via Termux.

## Why

Claude Code v2.1.113+ switched to native binaries, breaking Termux/Android compatibility. This repo provides:

- **v2.1.112** (last pure Node.js release) with auto-update protection
- **termux-chroot wrapper** that fixes the `/tmp` permission issue
- **mDNS resolver** for SSH without hardcoded IPs
- **Safe updater** that respects the version ceiling

## Requirements

- [Termux](https://f-droid.org/en/packages/com.termux/) (F-Droid recommended)
- Android 10+ (ARM64)
- ~500MB free storage
- An Anthropic API key or Claude subscription

## Quick Install

```bash
git clone <your-git-host>/<your-user>/claude-code-termux.git
cd claude-code-termux
bash install.sh
```

Or dry-run first:
```bash
bash install.sh --dry-run
```

## What Gets Installed

| Component | Location | Purpose |
|-----------|----------|---------|
| Claude Code v2.1.112 | npm global | The CLI itself |
| `clauded` | `~/.local/bin/` | Wrapper with termux-chroot for /tmp |
| `claude-check-env` | `~/.local/bin/` | Environment validator |
| `claude-update` | `~/.local/bin/` | Safe updater (ceiling-aware) |
| `mdns-resolve` | `~/.local/bin/` | Pure Python mDNS resolver |
| `mdns-publish.py` | `~/.local/bin/` | Publish this device as `movil.local` (needs `zeroconf`) |
| `ssh-mdns-proxy` | `~/.local/bin/` | SSH ProxyCommand: mDNS → Tailscale |
| `ssh-fallback` | `~/.local/bin/` | SSH ProxyCommand: Tailscale → LAN fallback |
| `settings.json` | `~/.claude/` | Disables auto-updater |

## Usage

```bash
# Start Claude Code (always use this, not `claude` directly)
clauded

# Check environment
claude-check-env

# Update (safe, respects version ceiling)
claude-update
```

## SSH with Dynamic Resolution

The included `ssh-mdns-proxy` resolves hostnames via mDNS first, then Tailscale DNS, then cache. See `config/ssh_config.example` for setup.

```bash
# Set your Tailscale domain (optional, has a default)
export TAILSCALE_DOMAIN="your-tailnet.ts.net"
```

## Version Ceiling

**v2.1.112 is the last compatible version.** Starting v2.1.113, Claude Code ships native binaries requiring glibc/musl linkers that don't exist on Android (Bionic libc).

`claude-update` enforces this automatically. See `docs/TROUBLESHOOTING.md` for details.

## Docs

Step-by-step guides for each piece of the stack:

| # | Doc | Covers |
|---|-----|--------|
| 01 | [docs/01-termux-fresh-install.md](docs/01-termux-fresh-install.md) | Clean Termux install (F-Droid / GitHub Releases, not Play) |
| 02 | [docs/02-base-packages.md](docs/02-base-packages.md) | Required `pkg` / `pip` / `npm` packages |
| 03 | [docs/03-ssh-mdns-tailscale.md](docs/03-ssh-mdns-tailscale.md) | SSH, `.local` resolution, Tailscale |
| 04 | [docs/04-samba.md](docs/04-samba.md) | Samba server on port 4450 + `msg.lock` gotcha |
| 05 | [docs/05-claude-code.md](docs/05-claude-code.md) | Claude Code internals (version ceiling, `clauded`, settings) |
| — | [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | Common errors and fixes |

## Troubleshooting

See [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) for:
- `/tmp` permission errors
- Native binary errors
- Auto-updater issues
- SSH resolution problems

## License

MIT