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.

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

What it can do

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.

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

Remote Control: a Claude Code session in your Claude app

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.

When an agent is using your phone

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 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.

The bubble

Developer mode: building apps

Off by default. When it's on, the agent may run commands and create or edit files in ~/.buddy/work inside Buddy's Linux. 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.

Security

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 six 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.

• 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.

FAQ

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.

Why isn't it on Google Play? Play's accessibility policy doesn't allow AI agents that operate other apps. Updates come from this repo: Buddy tells you when one 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.

Contributing

Bug reports and ideas are welcome in Issues, and pull requests too. If Buddy is useful to you, a ⭐ helps other people find it.

For developers

Build

Android Studio / Gradle

./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.

On the phone, without Gradle

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.

Project layout

License

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. Not on Google Play: Play's accessibility policy doesn't allow AI agents that operate other apps.