<p align="center"> <img src="docs/banner.png" alt="Buddy: Claude Code, Codex and OpenCode in a bubble on your Android phone" width="100%"> </p> <p align="center"> <a href="https://github.com/ghorbelhamdi/buddy-android/releases/latest"><img src="https://img.shields.io/github/v/release/ghorbelhamdi/buddy-android?style=for-the-badge&label=release" alt="Latest release"></a> <a href="https://github.com/ghorbelhamdi/buddy-android/releases"><img src="https://img.shields.io/github/downloads/ghorbelhamdi/buddy-android/total?style=for-the-badge" alt="Downloads"></a> <img src="https://img.shields.io/badge/Android-11%2B-3DDC84?style=for-the-badge&logo=android&logoColor=white" alt="Android 11+"> <a href="LICENSE"><img src="https://img.shields.io/github/license/ghorbelhamdi/buddy-android?style=for-the-badge" alt="License: Apache-2.0"></a> </p>

Buddy

A floating chat bubble that lets Claude Code, Codex or OpenCode use your Android phone.

Type or say what you want ("reply to Sam that I'm running late", "add a Nintendo Switch 2 to my Amazon cart") and Buddy reads the screen, taps, types and scrolls to get it done. It asks you before anything that sends, posts, buys or deletes.

It runs on your own subscription: Claude Code with your Claude plan, Codex with your ChatGPT plan, or OpenCode with its free models and no account at all. Everything runs inside the app, in Buddy's own small Linux on the phone: no PC, no adb, no root, no API key.

<p align="center"><a href="https://github.com/ghorbelhamdi/buddy-android/releases/latest/download/buddy.apk"><b>⬇ Download buddy.apk</b></a> · Android 11+, 64-bit · <a href="#setup">Setup</a> · <a href="#faq">FAQ</a></p> <div align="center">

https://github.com/user-attachments/assets/6659a546-9bbd-4adf-bb42-d924cf58e98e

_{Turning on the lights, then a pizza order changed mid-task (sped up)}

</div> <table> <tr> <td width="33%" align="center"><img src="docs/screens/chats.jpg" alt="Chats with Claude Code, Codex and OpenCode"><br>_{Chats with any of the three agents}</td> <td width="33%" align="center"><img src="docs/screens/chat.jpg" alt="A chat with grouped tool calls"><br>_{Tool calls fold into one line}</td> <td width="33%" align="center"><img src="docs/screens/settings.jpg" alt="Settings"><br>_{Setup guide and themes}</td> </tr> </table>

What it can do

<table> <tr><td><b>Uses your apps for you</b></td><td>Messages, shopping, smart home, settings, games: anything on screen. Add instructions while it works, by typing or by voice.</td></tr> <tr><td><b>Your agent, your plan</b></td><td>Claude Code (Opus, Sonnet, Haiku…), Codex, or OpenCode's free models. Pick the model per chat.</td></tr> <tr><td><b>Asks before it acts</b></td><td>Approve, Deny, or <b>Change</b> ("make it 9, add a smiley") before anything is sent, posted, bought or deleted. Messaging, shopping and money apps start on a <b>hard limit</b> that Buddy itself enforces.</td></tr> <tr><td><b>Asks when it's unsure</b></td><td>Questions come as a card with answer buttons, or type your own answer.</td></tr> <tr><td><b>Voice</b></td><td>Talk to it with the phone's recognizer, Claude's or ChatGPT's dictation, and hear replies in ChatGPT's voices.</td></tr> <tr><td><b>Phone tools for your own sessions</b></td><td>The same tools as a local MCP server, for Claude Code, Codex or OpenCode in any terminal, or a Remote Control session in your Claude app.</td></tr> <tr><td><b>Builds apps</b></td><td>In developer mode: "make me a calculator app" builds and installs a real APK, on the phone.</td></tr> <tr><td><b>Updates itself</b></td><td>A notice when a new version is out, or just ask: "update yourself".</td></tr> </table>

Status: 2.1, early. It works well day to day but still has rough edges. Tested on a OnePlus 12 (OxygenOS, Android 16); other Android 11+ phones should work, but may need battery settings adjusted.

Buddy is an independent project. It is not made by or affiliated with Anthropic or OpenAI.

Not another adb setup

Most "AI controls my phone" projects drive the phone over adb, which needs a computer or Wireless debugging that drops all the time. Buddy doesn't use adb at all:

• It's a normal Android app with an accessibility service, the same kind of permission screen readers use.
• No adb, no Wireless debugging, no PC, no root.
• Works without Wi-Fi and comes back on its own after a reboot.

How it works

Buddy app / bubble ──► Buddy's Linux (Alpine via proot): buddy-run ──► claude -p, codex exec or opencode run
        ▲                                                                  │
        └────────────── streamed replies (POST /event) ◄───────────────────┤
                                                                           ▼
Buddy accessibility service ◄──── MCP over http://127.0.0.1:8765/mcp (phone tools)

• The accessibility service draws the bubble and runs a small local MCP server with the phone tools: read_screen, tap, long_press, type_text, scroll, swipe, press, open_app, list_apps, open_url, screenshot, wait, install_apk, wait_for_install, confirm, ask, notify and update_buddy.
• Buddy's Linux is a small Alpine Linux that Buddy downloads into its own storage (4 MB) and runs with proot, which ships inside the APK. Claude Code installs there with Anthropic's official installer; Codex and OpenCode from npm.
• Your message goes to the agent in Buddy's Linux, which uses those tools and streams its progress back to the app.

Setup

You need a 64-bit Android 11+ phone and a Claude Pro/Max plan (or a ChatGPT plan for Codex). With OpenCode you don't need any plan: its free models work right away.

1. Install Buddy: download the APK and open it (allow your browser to install apps when asked). All versions are on the Releases page.
2. Follow the setup guide. It opens on first launch (later: Settings → Setup → Open the step-by-step guide). Each step ticks itself off when you come back.

| Step | What happens | |---|---| | Choose your agent | Claude Code (recommended), Codex, OpenCode (free models, no account), or Claude Code and Codex together | | Accessibility | Turn on Buddy assistant. Greyed out ("Restricted setting")? App info → ⋮ → Allow restricted settings, then try again | | Install and sign in | One tap installs your agent in Buddy's Linux (Claude Code about 235 MB, Codex about 150 MB, OpenCode about 230 MB; use Wi-Fi). OpenCode needs no sign-in; its providers can be connected later with Connect a provider, which runs opencode auth login in Buddy's terminal. For the others, Sign in: your browser opens, you approve, and Buddy comes back by itself. For Claude, Buddy picks the one-time code off the confirmation page for you. No browser on this phone you want to use? Sign in on another device (Claude: a link to open anywhere) or Sign in with a code (Codex) | | Keep it running | Battery: unrestricted for Buddy | | Try it | A first chat with a ready-made prompt |

Android blocked the install? Play Protect may say "App blocked to protect your device" for apps that use Accessibility and come from a browser: tap More details → Install anyway (or install from a file manager). On Android 13+, if Buddy assistant is greyed out in Accessibility, open App info → ⋮ → Allow restricted settings first.

Updating

Buddy isn't on the Play Store (Google doesn't allow its accessibility use or the agents it downloads), so updates come from GitHub Releases. Every release is signed with the same key, so installing a new APK over the old one keeps your chats, settings, sign-ins and Buddy's Linux. Don't uninstall first: that deletes them.

Ask Buddy: "Is there a Buddy update?" or "Update yourself." The agent checks the latest release, tells you what's new, and with your OK downloads buddy.apk from this repo's releases and opens Android's installer; you tap Update.

Automatic updates with Obtainium (free, open source; it checks GitHub for you and installs new versions):

1. Install Obtainium (from its website, F-Droid or IzzyOnDroid).
2. In Obtainium, tap Add App and paste https://github.com/ghorbelhamdi/buddy-android, then Add.
3. Each release has two identical APKs (buddy.apk and buddy-vX.Y.Z.apk). If Obtainium asks which one, pick buddy.apk. To never be asked, set Filter APKs by regular expression to ^buddy\.apk$ in the app's settings in Obtainium.
4. Obtainium now notifies you when a new version is out; tap Update and confirm Android's installer (the first time, allow Obtainium to install apps).

By hand: open the latest buddy.apk on the phone and install it over the current one. To get an email for each new version, sign in to GitHub and choose Watch → Custom → Releases on the repository.

Using Buddy

The app has three tabs: Chats, Sessions and Settings.

• Chats: start one with New chat (Claude Code, Codex or OpenCode; agents that aren't set up are greyed out), tap a chat to open it, long-press to delete it. Several chats can work at the same time.
• Models: tap the chip under a chat's title to pick the model for that chat (Opus, Sonnet, Haiku, Fable, Codex's own list, OpenCode's models including the free ones, or any model name). The conversation continues with the new model.
• Photos and files: tap the paperclip to take a photo, pick photos, or attach any file up to 25 MB.
• Voice: tap the mic to talk; the box turns into a recording bar (✕ cancel, live waveform, ↑ send). Choose the engine in Settings → Voice: the phone's recognizer, Claude (Claude Code's own dictation, on your Claude plan) or ChatGPT (ChatGPT's voice through Codex, on your ChatGPT plan; any language, even mixed). Claude and ChatGPT are greyed out until Claude Code or Codex is signed in. Pick your languages there; long-press the mic to switch.
• Read aloud: the speaker button reads replies, in the phone's voice or in ChatGPT's voice (Juniper, Maple, Ember, Cove: Settings → Voice → Voice output).
• Add instructions while it works: type or talk while a task runs; the agent gets it at its next step, without stopping.
• Tool calls fold into one "N tool calls" line you can open.
• Approvals appear in the chat and in the bubble: Approve, Deny, or Change: type or say what to adjust ("make it 9, add a smiley"), and the agent revises the message, post or email and asks again.
• Sessions: every Claude Code, Codex and OpenCode process in Buddy's Linux, with a Stop button. Recent sessions can be read, or continued in Buddy.
• Settings: setup, appearance (light/dark/system, accent colour, surface), agents (install, sign in, sign out), voice, the bubble, app permissions, developer mode and Remote Control.
• Terminal: a real terminal for Buddy's Linux (Sessions → Terminal): tabs, text selection and copy, links, pinch to zoom. Claude Code's, Codex's and OpenCode's own screens run in it.

Phone tools in your own sessions

Buddy's phone tools are a regular MCP server on the phone (http://127.0.0.1:8765/mcp, with a per-install token). Settings → Phone tools in your own sessions shows a ready-made command for Claude Code (claude mcp add …), Codex (codex mcp add …) and OpenCode (an OPENCODE_CONFIG_CONTENT line for ~/.bashrc), with a Copy button. Run it once in any terminal on the phone (Termux, for example), and every session of