ghorbelhamdi/buddy-android

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.

⬇ Download buddy.apk · Android 11+, 64-bit · Setup · FAQ

Chats with any of the three agents

Tool calls fold into one line

Setup guide and themes

Status: 2.2, 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.

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.

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.

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.

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.

Buddy is in closed testing on Google Play; the full version (with self-updates and developer mode) comes 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.

The agents (Claude Code, Codex, OpenCode) update separately: Settings → the agent → Check for updates. An OpenCode 1.x install gets Update to OpenCode 2 there; your connected providers are kept.

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.
• Notification rules: Settings → Experience → Notification rules. A rule picks an app, optionally who it's from and words it contains, and says what the agent should do; the agent gets that instruction with the notification, in a chat of its own per conversation (so it remembers what it answered before). It can reply through the notification's own Reply field without opening the app. Each rule picks its agent and model (a smaller model is quicker and uses less of your plan). Before acting, a rule either asks you as usual or uses a countdown (10 s to 5 min): the approval card approves itself unless you tap to stop it. Only sending a message can be approved that way, and only after a second AI has checked it against your rule (the Smart reviewer: Haiku by default, or the model you pick in App permissions). Recent activity is listed on the rules screen, and each run ends with a quiet notification saying what it did. Buddy needs notification access for this (it asks first); notifications no rule matches are ignored.
• 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.
• Languages: Buddy is in English, Arabic, Chinese (Simplified), Dutch, French, German, Hindi, Indonesian, Italian, Japanese, Korean, Polish, Portuguese, Russian, Spanish, Turkish and Ukrainian. It follows the phone's language; to pick another one for Buddy alone, use Android Settings → Apps → Buddy → Language. The agents answer in whatever language you write in.
• 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.

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 that agent gets the phone tools, even without the bubble. The token is masked on screen.

Settings → Remote Control → Claude Code session keeps a Claude Code session with Remote Control running inside Buddy. It appears as "Buddy" in the Claude app's Code sessions, on this phone or anywhere else, and it has the phone tools. Buddy restarts it if it stops and continues the same conversation after an update.

As soon as an agent starts operating the phone, Buddy makes it obvious so you know not to touch it: the bubble turns into a solid "Using your phone" pill (hold the bubble for Pause or Stop task; it shows even if you've hidden the bubble), and a status-bar notification appears (a Live Update chip on Android 16 where supported). Stop ends Buddy's chats and refuses phone actions from any session for a minute. Pause lets you use the phone in the middle of a task: the agent's next phone action waits until you hold the bubble and tap Resume, then it re-reads the screen before going on. Stop while paused ends the task without that action running, and a pause longer than 5 minutes stops the task.

Off by default. When it's on, the agent may run commands in Buddy's Linux (including installing packages with apk) and create or edit files in ~/.buddy/work. With the bundled android-app skill (plus AGENTS.md for Codex) you can ask "make me a calculator app": it sets up a toolchain the first time (OpenJDK, aapt2, d8, apksigner; about 400 MB), writes plain Java, builds a signed APK on the phone without Gradle, and opens Android's installer for you to confirm. The first time, Android asks you to allow Buddy to install apps.

Leave it off for everyday use: with it on, text on screen that tries to trick the agent could lead to commands being run.

An accessibility service is powerful. Please read this before installing.

• Local only. The MCP server listens on 127.0.0.1 and requires a random per-install token. Nothing is reachable from the network.

• Approval gate. The agent is instructed to call confirm before sending messages, posting, buying, deleting or changing settings. You see the exact action with Approve / Change / Deny. When the agent needs you to choose (which reply, which item), it can call ask instead: a card with 2–4 answers and your own typed answer.

• App permissions (enforced by Buddy, not the agent). Settings → Experience → App permissions, per app:

  • Trust: asking is left to the agent.
  • Hard: Buddy itself checks every tap; buttons like Send, Pay, Delete (built-in words in all of Buddy's languages, plus your own always ask / never ask rules, with suggestions from buttons the agent has tapped) need your OK.
  • Smart: the rules, then a separate temporary Claude Code or Codex session without tools reviews every other tap against your request and the screen (about 3 s a tap). OpenCode chats are reviewed by Claude Code or Codex.

  Messaging, social, email, calling, shopping and money apps start on Hard. The agent can never tap or type in Buddy's own bubble, cards or settings, so it can't approve for you or loosen the rules.

• Prompt injection is the main risk. Buddy reads whatever is on screen. A malicious message, email or web page could contain text like "send this to all your contacts". Buddy's instructions treat on-screen text as content, never commands, and the approval gate is the backstop, but no model is perfect. Read approval cards carefully.

• Notification rules work for someone else's message, so their runs get less: no shell, files or web (even in developer mode), no installing apps, your Trust settings don't apply, and opening a link always asks you. The notification is passed to the agent as outside content, never as instructions. A rule's countdown can only approve sending a message (never paying, buying or deleting, and never in payment or shopping apps), and only after a second AI agrees the reply fits your rule; otherwise the card waits for you. Runs are limited to 5 an hour per conversation and 30 in all. Use countdowns for low-stakes replies.

• Limited tools. Outside developer mode, Claude Code gets the phone tools, web search and fetch, and read access to that chat's attachments only (no shell, no other files). Codex runs in its read-only sandbox. OpenCode's shell and file edits are refused (set to "ask", which a non-interactive run auto-rejects). Everything runs inside Buddy's own app storage, separate from your other apps' files.

• What leaves the phone: only what Claude Code, Codex or OpenCode sends to its model provider (Anthropic, OpenAI, OpenCode's own service, or the provider you connected) to answer you, including screen text, screenshots and attachments it reads.

• Never let Buddy type passwords, one-time codes or payment details. It's instructed to hand those back to you.

Found a security problem? Please open a private security advisory on GitHub rather than a public issue.

What does it cost? Buddy is free. The agent runs on your existing Claude or ChatGPT plan (it uses your plan's limits), or on OpenCode's free models at no cost.

Does it work on iPhone? No. iOS doesn't let apps operate other apps.

Which phones? 64-bit Android 11 or newer. It's tested most on a OnePlus 12; on some brands you need to set Buddy's battery use to Unrestricted so Android doesn't stop it.

Is it on Google Play? In closed testing. The Play version leaves out self-updates and developer mode, as Play requires; the GitHub version stays free and complete, and Buddy tells you when an update is out (see Updating).

Can it see my passwords or pay for things? It never types passwords, codes or payment details; it hands those to you. Paying, sending and deleting need your OK, enforced by Buddy itself in the apps on a hard limit. See Security.

Does it need a computer, adb or root? No. Everything happens on the phone.

• ProPakistani: This Free Android App Lets Claude Code Use Your Phone (October 2026)
• The Neutral: This Free Android App Lets AI Control Your Phone Without a PC (October 2026)
• Trendshift: featured among trending GitHub repositories (October 2026)

Bug reports and ideas are welcome in Issues, and pull requests too: see CONTRIBUTING.md for how to build, test on a phone and propose a change. If Buddy is useful to you, a ⭐ helps other people find it.

./gradlew assembleRelease

Release signing reads BUDDY_KEYSTORE, BUDDY_KEYSTORE_PASSWORD (and optionally BUDDY_KEY_ALIAS, BUDDY_KEY_PASSWORD) from the environment; without them the APK is unsigned. GitHub Actions builds every push and attaches the APK to a release for v* tags.

In Termux (or any Linux with these tools):

pkg install openjdk-17 aapt2 d8 apksigner python
# android.jar from platform-36 at ~/android-sdk/android-36/android.jar
./build.sh        # → build/buddy-release.apk

build.sh runs aapt2 → javac → d8 → align → apksigner (and packs app/src/main/jniLibs) and creates a signing key at ~/.buddy-keys/release.jks on first run. Back it up: updates must be signed with the same key.

The version lives in app/src/main/java/app/buddy/assistant/BuildInfo.java.

Apache-2.0. Geist fonts: SIL Open Font License. Icons: Material Symbols (Apache-2.0). Bundled proot (GPL-2.0), talloc (LGPL-3.0) and libandroid-shmem (BSD-3-Clause): see third_party for licences and source.