Claude Code on Android

[!TIP] Upgrading, or hitting a launch error or a "Checking connectivity" hang? See Troubleshooting for the recovery steps. Your login and settings are kept.

---

Before You Start

What you need in place before any command in this guide can succeed:

These three prerequisites are for Path A and Path B, which both run in Termux. Path C, which runs on the Android Virtualization Framework (AVF, Android's built-in support for running a real Linux virtual machine), does not use Termux at all: it needs a Pixel 6 or later on Android 16 or later with Developer options turned on. If that is your setup, skip ahead to Path C: AVF Linux VM.

1. An aarch64 (64-bit ARM) Android phone, Android 8 or later. Most Android phones from 2018 onward qualify. A few budget Samsung A-series models ship a 32-bit OS on 64-bit hardware and will not work; see the Troubleshooting entry on armv7l / armv8l if uname -m (a command that prints your device's CPU architecture) returns those once you have a terminal open.
2. A Claude account (Pro, Max, Team, Enterprise, or a Console / API account, meaning a pay-as-you-go developer account at console.anthropic.com). Claude Code uses your existing Anthropic login.
3. Termux installed from F-Droid or GitHub. Termux is the terminal-emulator app the install commands below run in. The upstream Termux maintainers recommend F-Droid or their GitHub releases for most users. There is a Google Play build but as of the upstream README it is an experimental branch with missing functionality and bugs, and the upstream project recommends against it for most users. See github.com/termux/termux-app for the full install source breakdown and current caveats from the Termux maintainers themselves.

If you have never used F-Droid or Termux before, the upstream maintainers already cover the install steps better than this repo can:

• F-Droid (the open-source Android app store you install as an APK): f-droid.org. The front page has the install instructions and the Play Protect prompt you may see on first launch.
• Termux on F-Droid: f-droid.org/en/packages/com.termux/. You can install F-Droid first and then install Termux from inside it, or download the Termux APK directly from that page.
• Termux project (background, FAQ, troubleshooting): github.com/termux/termux-app, wiki.termux.com.

Once Termux is open you will see a prompt that looks like ~ $. That is where the commands in Quick Install go. (Long-press to paste, or tap the on-screen Ctrl key then press V.)

Full prerequisites including the Termux:API source-matching rule: docs/install.md#prerequisites.

---

Quick Install

The repo documents three install paths. Pick one before pasting commands:

• Path A (native Termux). The official linux-arm64 claude binary, patched to run on Android, with a wrapper that checks once a day for a new version and updates transparently. About 5 to 10 minutes to install, a few hundred megabytes on disk, and about 200 MB more if you accept the recommended packages. One thing to know up front: on launch it points Claude Code's own DNS lookups at Google's public resolvers (8.8.8.8 / 8.8.4.4) to sidestep a connectivity hang, which overrides a VPN, split-tunnel, or Pi-hole resolver for those queries (see Security Model).
• Path B (proot-distro Ubuntu). Latest Claude Code installed via Anthropic's official installer inside a full Ubuntu environment. Heavier at ~2 GB on disk, but process.platform reports linux and standard Linux conventions all apply. (process.platform is the runtime identifier of the host operating system, which some tools branch on.)
• Path C (AVF Linux VM, experimental). Real Linux kernel via Android's built-in virtual machine support (the hypervisor). Doesn't use Termux at all. Needs a Pixel 6 or later on Android 16 or later. The Exynos Galaxy S26 / S26+ are reported to work but I have not lab-verified them; Snapdragon devices, including the S26 Ultra, are not supported.

Which should you pick? Path A is the default: it is what install.sh sets up, and it keeps itself current, so if you are not sure, start there. My own take on the tradeoffs is in the note below. Side-by-side comparison: docs/install.md#choose-your-path.

[!NOTE] Which path I run, and why: I run Path A (native Termux) myself. It is what install.sh sets up, it keeps itself current, and it is what I migrated my own daily driver to. If you would rather keep a patched-binary wrapper out of the loop, Path B (proot-distro Ubuntu) is the simplest way to keep Claude Code self-updating through Anthropic's official installer, the same as on a PC. Path C (AVF) is arguably the most genuinely native option, though its coverage is still narrow. Pick the one that fits your device; I am just sharing what I run.

If you are coming up from an older pinned 2.1.112 install, follow Upgrading from a pinned install. Not sure which install you have? claude --version reports Claude Code's own version (the 2.1.x number), not this repo's, so it will not tell you; see Which setup am I on? for a one-command check.

Path A: Native Termux

curl -fsSL https://raw.githubusercontent.com/ferrumclaudepilgrim/claude-code-android/main/install.sh -o install.sh
bash install.sh

The installer asks two yes/no questions, then runs unattended. When it finishes, type:

claude

Here is what install.sh does, start to finish:

• Installs Termux's glibc-runner and patchelf-glibc.
• Downloads the official linux-arm64 claude binary from Anthropic's CDN (the content-delivery servers the file is hosted on) and verifies the checksum (a fingerprint that confirms the download arrived intact from Anthropic) against Anthropic's published list. The binary and its checksum come from the same Anthropic host, so this catches a corrupted or truncated download; it is not upstream code signing and does not by itself prove the source was not compromised.
• Patches the binary's ELF interpreter so Android can run it. ELF (Executable and Linkable Format) is the standard format for Linux programs, and the "interpreter" is the loader it asks for at startup; this step points the binary at the Termux-provided one.
• Drops a wrapper at $PREFIX/bin/claude ($PREFIX is Termux's own install folder) that auto-checks for new claude releases once a day on launch.

The wrapper accepts a --update-now flag to force an immediate check; this is a Path A wrapper feature, not a built-in Claude Code flag. Want to read it first? View install.sh on GitHub before running.

Full walkthrough: docs/install.md.

Prefer the smallest, simplest install and do not need current claude? install-pinned.sh pins Claude Code 2.1.112 (the last version with a JS entry point) with no binary patching and no auto-updating wrapper. It stays at that version; install.sh above is the default for current claude.

[!IMPORTANT] Path A runs on a compatibility workaround. Anthropic ships Claude Code as a glibc-linked Linux binary, with no Android build. Termux runs on Android's Bionic C library, so any version past the old pinned 2.1.112 runs here only because install.sh patches the official linux-arm64 binary to load through Termux's glibc-runner. It works and stays current, but it is a shim, not native support.

The real fix is upstream. There is no official Android build today; adding one would need either a bun android-arm64 target or a static musl build. (bun is the JavaScript runtime Claude Code is bundled with; a static musl build would be a fully self-contained binary that does not rely on the host system's C library.) Until that ships, Path A depends on this patching step. Tracked at anthropics/claude-code#50270.

Path B: proot-distro Ubuntu

Latest Claude Code inside a full Ubuntu environment.

pkg install proot-distro -y
proot-distro install ubuntu && proot-distro login ubuntu

This may take a few minutes depending on connection speed.

Upon completion the prompt changes to something like:

root@localhost:~#

That means you are now inside Ubuntu rather than Termux. Inside Ubuntu:

apt update && apt upgrade -y
curl -fsSL https://claude.ai/install.sh | bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
claude

Full walkthrough: docs/install.md#path-b-proot-distro-ubuntu.

Path C: AVF Linux VM (Pixel 6+ with Android 16+, experimental)

Real Linux kernel via the Android Virtualization Framework. No Termux involved. Supported on Pixel 6 and later. The Exynos Galaxy S26 / S26+ are reported to work but I have not lab-verified them; Snapdragon devices, including the S26 Ultra, are not supported.

On the phone, open Settings > System > Developer options and toggle Linux development environment on. If Developer options is not visible, enable it first: Settings > About phone > tap Build number 7 times. (You only have to do this once per phone.) If the Linux development environment toggle still does not appear after enabling Developer options, your device does not support this path.

Open the Terminal app that appears on the home screen. Accept the prompt to download the Debian image. When the prompt shows droid@debian:~$, install Claude Code inside the VM:

curl -fsSL https://claude.ai/install.sh | bash
export PATH="$HOME/.local/bin:$PATH"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
claude

The Terminal app's gear icon opens Settings, with Memory size, Display resolution, and Keep awake controls under Advanced. Full walkthrough including ADB hardware bridge, recovery, and known issues: docs/avf-guide.md.

---

What's In This Repo

Guides

Document	Covers
docs/install.md	Full step-by-step setup for all three paths, verification, maintenance
docs/faq.md	Install gotchas, path-choice questions, Android-version-specific behavior
docs/troubleshooting.md	Symptom-shaped entries: errors, hangs, failures with their fixes
docs/skills.md	Claude Code skills shipped in .claude/skills/ and scripts under scripts/
docs/adb-wireless.md	ADB self-connect: setup, security model, capability table
docs/security-model.md	What Claude Code can and cannot reach on your phone: Termux:API permissions, ADB access, and the limits on each
docs/agent-permissions.md	A rule set so no single automated helper can both read the web and write files (limits what a bad instruction could do)
docs/ssrf-guard.md	An optional safety check that stops the web-fetch tool from reaching private or internal network addresses
docs/fingerprint-gate.md	An optional fingerprint prompt before risky actions, using Termux's termux-fingerprint
docs/constitution-template.md	CLAUDE.md template with Android/Termux constraints baked in
docs/avf-guide.md	Path C (virtual machine) setup, configuration, and hardware bridge
docs/sensors.md	Reading device sensors from Termux using Android's native development kit (NDK)

Tools

Item	Does
install.sh	Path A installer (patched linux-arm64 binary + auto-updating wrapper)
install-pinned.sh	Opt-in pinned installer (Claude Code 2.1.112, no patched binary, no auto-update); stays pinned
migrate.sh	Upgrade a pinned v2.x install to the current auto-updating architecture, preserving sessions, login, and settings
scripts/	check-termux-env.sh, config-validator.sh, and recovery helpers
.claude/skills/	minimum-viable, scope-framing, termux-safe
tests/	verify-claims.sh (per-claim PASS/FAIL/SKIP harness); ssrf-guard-tests.sh

Project

CHANGELOG.md	Version history from 0.1.0 forward
CONTRIBUTING.md	How to contribute, report bugs, submit device reports

---

Device Compatibility

Per-device verification dates. Android 10 and 8 cannot run the native binary: it trips Android's seccomp filter (the kernel feature that blocks certain low-level system calls) and crashes on launch, so those devices stay on the pinned 2.1.112 install (install-pinned.sh). Rows link a saved verify-claims.sh transcript where one exists; rows marked ¹ were confirmed by hand on the date shown. This repo's version and Claude Code's own version are different numbers: see Which setup am I on?.

Device	Android	Path A	Path B	Test artifact
Google Pixel 10 Pro 2	17	✅ (2026-07-26) 31	✅	pixel-10-pro-android17.txt (v2.x)
Google Pixel 6 2	17	✅ (2026-07-27) 31	✅ 1	doc-only
Motorola Moto G7 Power	10	pinned only (2026-07-27) 4	✅	moto-g(7)-power-android10.txt (v2.x)
Samsung Galaxy S7 (SM-G930P)	8	pinned only (2026-07-26) 5	✅ (manual URL paste)	sm-g930p-android8.0.0.txt (v2.x)
Samsung Galaxy S26 Ultra	16	✅ (2026-05-29) 61	✅ 1	doc-only
Samsung Galaxy S23+	15	n/a	✅ (2026-03-19) 1	doc-only

Path C (AVF) re-verified on Pixel 6 and Pixel 10 Pro running Android 17 on 2026-05-26; see docs/avf-guide.md. Submit a device report if you've tested on hardware not listed.

---

Alternative: Remote Control

If you have a desktop or laptop running Claude Code, Remote Control lets you control it from your phone via QR code. Use Remote Control when you have a desktop nearby; use this repo when you want Claude Code running locally on your phone.

---

Other Projects, Other Ways In

I am not the only one solving this. Depending on what you want, one of these may fit you better than my scripts do:

• gtbuchanan/claude-code-termux is where the patched-binary approach started (also credited below). It wraps the same download-and-ELF-patch idea in a cleaner apt .deb package, so if you would rather install from a package than run a shell script, look here first.
• Ishabdullah/claude-code-termux is a short guide rather than a script: install the @anthropic-ai/claude-code npm package (npm is Node's package manager) and run claude through a shell alias. That is the same territory as my install-pinned.sh. Worth knowing it covers the versions that still ship a JavaScript entry point, not the current native binary.

One to steer around: techjarves/open-claude-code-termux is not this repo and not the same thing. Despite the name, it runs a leaked build against third-party OpenRouter models, not real Claude Code with your Anthropic login. If you want the actual product, that is not where to get it.

---

MCP, Voice, PDF, ADB

These features work on Android with specifics covered in their own docs.

• MCP (Model Context Protocol, the standard Claude Code uses to connect to external tools and data sources): Remote HTTP and local stdio transports work on both Path A and Path B. OAuth-based servers (servers that use the OAuth 2.0 authorization flow, which redirects through a browser to grant access tokens) depend on the Android browser being able to reach a localhost callback; reliability varies by path and device. See troubleshooting.
• Voice mode: The SoX → PulseAudio → backend chain has worked on the devices I have tried, though some vendor builds break at the OpenSL ES backend on older Android versions. Test before relying on it. Mic input is in flight via termux-packages#29074. (SoX is a command-line audio toolkit; PulseAudio is the Linux sound server; OpenSL ES is the Android audio API PulseAudio uses to reach the device speaker.)
• PDF reading: Requires a which shim; see troubleshooting.
• ADB wireless self-connect: Pair the phone to itself for system-level capabilities (screen capture, input injection, content queries). Full guide: docs/adb-wireless.md.

---

Contributing

Found a bug? Got it working on a new device? Know a better workaround?

• Bug reports: Open an issue
• Device reports: Submit compatibility data
• Improvements: PRs welcome. See CONTRIBUTING.md.

---

From the Maintainer

Ferrum_Flux_Fenice here, aka Erin. If you haven't noticed, the pushes have slowed over the last few months. Most of that is stability. Even with the regression that pinned older devices to 2.1.112, the community on the issue thread and having this amazing tool inside Termux, on the device, have helped tremendously. Over time I have been trying to build this into a lasting repo that helps as many people as it can. I have a few more things I am working on, for the repo and in general.

If you want to be a part of it, or you find something to contribute or something broken, open an issue or a pull request. I enjoy being able to put some time forward, learn, and help others.

I maintain this alone and I am not a security professional, so treat nothing here as canonical: verify everything before you rely on it.

@ferrumclaudepilgrim · Ferrum_Flux_Fenice (my project alias) · Erin

---

License

MIT. See LICENSE.

Built on and assisted by:

• Claude Code by Anthropic: anthropics/claude-code
• glibc-runner / patchelf-glibc: Termux's glibc-packages project that makes running linux-arm64 binaries on Android possible: termux/glibc-packages
• The patched-binary approach was originally described by gtbuchanan in a comment on anthropics/claude-code#50270. This repo's install.sh is built on top of that work with empirical verification, the auto-updating wrapper, and the interactive prompts added.
• Termux: the Android terminal that makes all of this possible: termux/termux-app

Maintained by @ferrumclaudepilgrim. Issues and pull requests welcome.

Footnotes

1. Verified by hand on the date shown. Any file linked in the last column is a transcript from an earlier run (its version is noted beside it); the date in this column was confirmed without a new captured transcript. ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷

2. Path C (AVF) was also verified on this device on 2026-05-26; see the note below the table and docs/avf-guide.md. ↩ ↩²

3. Path A here runs the native binary through the auto-updating wrapper, which tracks the latest claude release rather than pinning a version. ↩ ↩²

4. Path A here stays on pinned 2.1.112; the native binary is capped on Android 10. ↩

5. Path A here stays on pinned 2.1.112; the native binary is capped on Android 8. ↩

6. Verified on v2.9.0, installed via migrate.sh. ↩