Claude Code on Android

Run Claude Code natively on Android — no root, no emulator, no cloud VM.

Claude Code is Anthropic's AI coding assistant that runs in your terminal. It reads files, writes code, runs commands, and manages projects — all through conversation. This repo gets it running on an Android phone.

S26 Ultra (Android 16) · S23+ (Android 15) · Pixel 10 Pro (Android 16) · more screenshots

Install Guide · Troubleshooting · ADB Wireless · CLAUDE.md Template · Meet the Crew

From the developer: This guide looks long because we document every edge case we hit. The actual install is about 5 commands. If you just want to get started, jump straight to Path B Quick Start and come back here when something breaks.

Using ADB wireless debugging? Read the security considerations first.

Prerequisites

You need Termux installed from F-Droid (not the Play Store — the Play Store version hasn't been updated since 2020 and will not work).

Architecture check first. Open any terminal and run uname -m. You need aarch64 (64-bit ARM). If you see armv7l or armv8l, your device runs a 32-bit OS and Claude Code cannot work — no workaround exists. Some budget phones (Galaxy A13, A02S, M13) ship 32-bit Android on 64-bit hardware. See Troubleshooting.

Install Termux

1. Download F-Droid from f-droid.org. F-Droid is an app store for open-source Android apps — it's where the maintained version of Termux lives.
2. Open the downloaded APK. Android will block it. Go to Settings → allow "install unknown apps" from your browser.
3. After installing F-Droid, go back to Settings and disable "install unknown apps" from your browser. Keep it enabled only for F-Droid (it needs it to install apps).
4. Open F-Droid, search for Termux, install it.
5. Android may warn "unsafe app — built for an older version." Tap More details → Install anyway. This is safe — Termux targets an older API level for broader compatibility.

Install Required Packages

Once Termux is open:

pkg upgrade -y
pkg install proot-distro -y          # Required for Path B (recommended)
pkg install android-tools -y         # Required for ADB self-connect
pkg install termux-api -y            # Required for device API access

Then install the Termux:API companion app from F-Droid (search "Termux:API"). Both the termux-api package and the companion app are required -- the package provides the commands (termux-battery-status, termux-tts-speak, termux-notification, etc.) and the companion app provides the Android permissions bridge. Without both, API calls fail silently.

Source matching rule: Termux and Termux:API must come from the same source (both F-Droid or both GitHub releases). Mixing sources causes silent permission failures that are difficult to diagnose.

Already have Termux from F-Droid with packages installed? Skip to Quick Start.

Quick Start

There are two ways to install Claude Code on Android. Both require a Claude Pro or Max subscription.

Most users should start here.

Path B -- Recommended (Full Linux Environment)

The cleanest setup. Installs Ubuntu inside Termux using proot-distro — think of it as a lightweight Linux environment running inside your phone's terminal. Claude Code runs in a standard Linux environment with no workarounds needed.

proot-distro install ubuntu
proot-distro login ubuntu

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

Storage requirement: approximately 2 GB for the Ubuntu environment plus Claude Code.

Why pkg upgrade and apt upgrade first? Without updated SSL libraries, the Claude Code installer returns 403. Both upgrades are required.

Path A — Fully Viable with Node v25+

Faster setup (~2 min), less disk space, but requires workarounds that break on every Claude Code update.

pkg install nodejs git curl proot ripgrep -y
export TMPDIR=$PREFIX/tmp   # Critical: npm fails silently without this
npm install -g @anthropic-ai/claude-code
# Required: bare 'claude' will fail — always use this wrapper
proot -b $PREFIX/tmp:/tmp claude

Add this to ~/.bashrc so it persists:

echo 'export TMPDIR=$PREFIX/tmp' >> ~/.bashrc
echo "alias claude-android='proot -b \$PREFIX/tmp:/tmp claude'" >> ~/.bashrc
source ~/.bashrc

Scripted install: There's also a one-command installer for Path A.

Which Path Should I Use?

First timer? Use Path B. Fewer things break.

Path C -- Experimental (AVF Linux VM)

Android 16 on Pixel 6+ devices includes a built-in Linux VM via the Android Virtualization Framework (AVF). This gives you a real Linux kernel, native /tmp, and process.platform === "linux" -- no proot, no workarounds. RAM allocation is configurable via vm_config.json, ADB wireless debugging from inside the VM provides access to 42 phone sensors, GPS, camera, screen capture, and input injection. Headless GUI rendering is possible with native audio.

# Enable in: Settings > System > Developer Options > Linux development environment
# Open the Terminal app, wait for Debian image download (~761 MB)
# Inside the VM:
curl -fsSL https://claude.ai/install.sh | bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
claude

Limitations: VM may be killed when screen turns off (ADB whitelist commands improved stability in our testing but are not a complete fix). No Termux API access (camera, TTS, GPS, SMS). Samsung/Snapdragon devices not supported. See AVF-GUIDE.md for the full setup, VM configuration, ADB hardware bridge, security defaults, and three-path comparison.

This is experimental. Tested on a single Pixel 10 Pro. If you need stability, use Path A or B.

Your First Session

Once you've installed Claude Code and authenticated:

1. Create a project folder: mkdir ~/myproject && cd ~/myproject
2. Launch: claude
3. Try: "What files are in this directory?"
4. Type /help to see available commands
5. If you install the skills below, the /doctor skill (not the built-in claude doctor, which doesn't work in Termux) verifies your setup

Why This Is Hard

Running Claude Code on Android means solving problems that don't exist on desktop. Quick summary:

• /tmp does not exist. Claude Code needs /tmp for sockets. Android has none. Path A uses proot -b $PREFIX/tmp:/tmp; Path B has /tmp natively. You can also set CLAUDE_CODE_TMPDIR to any writable directory.
• Node.js v24 may hang. Specific to v24 on native Termux (aarch64). v25+ resolves it. Path B avoids Node entirely.
• Missing ripgrep binary. Claude Code ships no ARM64 Android build. Path A needs a symlink workaround (/fix-ripgrep skill). Path B uses Ubuntu's ripgrep.
• Platform detection mismatch. Native Termux reports android; proot-distro Ubuntu reports linux. Some tools behave differently or fail depending on which they detect.
• File paths vary by manufacturer. External storage paths, sdcard symlinks, and /proc layouts differ across Samsung, Pixel, OnePlus, and others. Test file operations on your specific device rather than assuming paths from documentation.

MCP (Model Context Protocol)

Two of three MCP transport types work on Android:

• Remote HTTP servers (e.g., Cloudflare) -- connect over HTTPS, zero local install. Best option for mobile.
• Local stdio servers (e.g., npx -y @modelcontextprotocol/server-memory) -- spawns child processes via npx. Tested with Node.js v25.8.1.
• OAuth-based MCP servers -- expected to fail. Termux provides xdg-open (symlink to termux-open) so browsers can launch, but OAuth redirect callbacks to localhost still fail because Termux has no loopback HTTP listener. Use token-based auth instead.

To add a remote MCP server:

claude mcp add --transport http <name> <url>

To add a local stdio server:

claude mcp add <name> -- npx -y <package>

ADB Wireless Self-Connect

By connecting your phone to itself over ADB wireless debugging, Claude Code gains access to system capabilities that Android normally blocks from Termux. No root required. No computer needed.

What ADB Unlocks

These work alongside Termux API features (camera, TTS, clipboard, GPS, SMS, notifications, sensors, vibration) which don't need ADB at all.

Security warning: ADB wireless debugging opens a network-accessible port on your device. Any device on the same WiFi network can attempt to pair. ADB requires a pairing code for every new connection, but the port is still exposed. Enable wireless debugging only when you need it. Disable it when you're done. On public WiFi, it must be off. The connection from Termux is localhost-only (127.0.0.1), so the ADB server itself does not listen on external interfaces from the Termux side, but the Android wireless debugging daemon does. This is the same risk every Android developer accepts when using wireless debugging. See ADB-WIRELESS.md for full security details.

Quick Setup

# In Termux (not inside Ubuntu):
pkg install android-tools -y

# On your phone: Settings → Developer Options → Wireless Debugging → ON
# Tap "Pair device with pairing code" — note the IP:port and pairing code

adb pair 127.0.0.1:<pairing-port> <pairing-code>
adb connect 127.0.0.1:<connection-port>
adb devices   # Should show your device

ADB works from inside the Ubuntu guest too. Setup takes about 5 minutes. See ADB-WIRELESS.md for the complete guide, security details, and persistence notes.

Requires WiFi. Android checks for a WiFi association (not internet access). ADB wireless disables automatically on mobile data.

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. No Termux needed.

Use Remote Control when you have a desktop nearby and want quick mobile access.
Use this repo's approach when you want Claude Code running locally on your phone with no desktop dependency.

What's In This Repo

Guides

Tools & Config

Project

Device Compatibility

Verified means install, authentication, and basic operations tested end-to-end on real hardware. Test results: tests/results/

Tested on your device? Submit a device report to help fill in the gaps.

PDF Reading

PDF reading requires which shim

Claude Code's PDF reader checks for pdftoppm using which, but Termux doesn't ship a which binary.

See Troubleshooting: PDF reading for the fix.

Known Constraints

Running on a phone means real limits. Path B (Ubuntu) resolves some of them.

See TROUBLESHOOTING.md for detailed fixes.

Skills

This repo includes Claude Code skills for Android and general-purpose workflow.

Android / Termux

See all skills including workflow tools that work in any environment.

Installing Skills

Copy them to your home directory so they work in any project:

cd ~
git clone https://github.com/ferrumclaudepilgrim/claude-code-android.git
mkdir -p ~/.claude/skills
cp -r claude-code-android/.claude/skills/* ~/.claude/skills/
ls ~/.claude/skills/
rm -rf claude-code-android   # Clean up — phone storage is finite

The CLAUDE.md Template

Claude Code reads a CLAUDE.md file from your project root for persistent rules. The template in this repo is designed for Android and Termux — it includes platform constraints, safety rules, and agent configuration for up to 6 concurrent agents.

The Agents

This repo is built and maintained by 6 specialized AI agents running concurrently on a single phone. See Meet the Crew for the full roster and how they work.

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.

About This Project

This repo is built and maintained using Claude Code running on the same Android device it documents — the tool documenting itself, on the platform it's documenting. The operator (FerrumFluxFenice) guides the work, Claude Code builds it, and every claim is verified on real hardware.

Claude Code is made by Anthropic. Official repo: anthropics/claude-code.

License

MIT. See LICENSE.

A note from the developer:

Thank you to anybody reading this. I hope you enjoy my repo and have success utilizing it. I am exploring the intricacies of development, GitHub (and git in general), learning and growing. This is a passion project of mine and I update it regularly as I plan to further my usage of Claude Code on Android and in the process contribute back to Termux, which is what made all of this possible. I am a 100% part-time indie doing this because I enjoy it.

If you find something broken, have a question, or want to contribute, open an issue or submit a PR. Every bit helps.

Built on Termux.

@ferrumclaudepilgrim

Built on a phone, in Termux, on ARM64, on Android.
By a human and an AI, working together.
v2.5.0