Reading the repo
Opening the box…
Reading the repo
Opening the box…
How to install on Linux
Android AI assistant in a floating bubble: Claude Code, Codex, OpenCode, Gemini (Antigravity CLI) or Grok use your phone for you — read the screen, tap, type. Runs on your own plan, open source, no root, no adb, no PC.
Saved setup from 8 h ago
Will it work on Linux?
CONTRIBUTING.mdThanks for helping. Bug reports, ideas and translation fixes are all welcome. Features and bug fixes are built in the project itself, so please open an issue for them rather than a pull request.
Open an issue with the bug form. The most useful details are your phone and Android version, the agent and model (Claude Code, Codex, OpenCode, Antigravity or Grok), what you asked, and what happened instead. A screenshot of the chat (open its "N tool calls" line) usually shows where it went wrong.
Found a way for an agent to act without your approval, or to approve for you? Please don't post it publicly: see SECURITY.md.
See For developers in the README: ./gradlew assembleRelease, or ./build.sh right on the phone in Termux.
bash linux/test/run.sh feeds recorded runs of each agent (linux/test/fixtures) through linux/buddy-run and compares the events. CI runs it too.
There are two flavors: github (the release on GitHub, which updates itself) and fdroid (the same app without the self-updater: F-Droid builds, signs and updates it).
Buddy's English text is in app/src/main/res/values/strings.xml, and each language has its own values-<code>/strings.xml. The first translations were made with AI, so corrections from native speakers are very welcome.
values/strings.xml to values-<code>/strings.xml, translate it (leave out entries marked translatable="false") and add the code to res/xml/locales_config.xml, so it shows up in Android's per-app language setting.%1$s and %2$d exactly, and escape apostrophes as \'.values/strings.xml; until it's translated, other languages show it in English.Buddy is Apache-2.0. By opening a pull request with a translation you agree that it is released under the same license.
| Path | What it is |
|---|---|
| app/src/main/java/app/buddy/assistant/BuddyService.java | Accessibility service: hosts the bubble, the MCP server and the in-control indicator |
| .../Tools.java | The phone tools |
| .../McpServer.java | Minimal MCP server (streamable HTTP, JSON responses) |
| .../Bubble.java | The floating bubble and its chat panel |
| .../AutoPause.java, Marks.java | Pausing when you take the phone back (a touch, a call), and the marks point_out draws on the screen |
| .../MainActivity.java, ChatActivity.java, MonitorActivity.java, SetupActivity.java | Chats, a chat, Sessions, Settings |
| .../OnboardingActivity.java | First-run setup guide |
| .../ChatHub.java, Sessions.java | Chat state shared by the app and the bubble |
| .../Rules.java, RulesActivity.java, NotificationWatcher.java, Triggers.java, Waiting.java, WaitingActivity.java | Notification rules: the rules and their screen, notification access, the runs they start, and the replies waiting for your OK |
| .../Ui.java, Theme.java | Components and the light/dark/accent theme |
| .../Linux.java | Buddy's Linux: downloads Alpine and runs commands through proot |
| .../Helper.java | Runs buddy-run inside Linux and keeps its files up to date |
| .../Account.java, SignInActivity.java | Install, one-tap sign-in and status for Claude Code, Codex, OpenCode, Antigravity and Grok |
| .../RemoteSession.java | The Remote Control session |
| .../CodexRemote.java | The Codex session: runs linux/codex-remote and passes on pairing requests |
| .../SshServer.java | SSH from Termux: the server in Buddy's Linux and the one-time code that lets a key in |
| app/src/main/res/values/strings.xml | Every text Buddy shows, in English; values-<language>/ holds the translations |
| app/src/main/jniLibs/arm64-v8a/ | proot and its libraries (see third_party) |
| linux/buddy-run | Runs the agent with the phone tools and streams events back |
| linux/codex-remote | Codex's app-server with remote control and the phone tools; makes pairing codes in the same proot |
| linux/system-prompt.md | Buddy's instructions for the agent |
| linux/android-app/ | The developer-mode skill: toolchain setup and build-apk.sh |
| app/src/main/assets/linux | Symlink to linux/, so the helper ships inside the APK |
Then run bash setup.sh. It stops at the first error and is safe to run again. Servers and tests aren't started; it lists them at the end. Read it first.
The repo uses git submodules, so the clone fetches them too.
git clone --recurse-submodules https://github.com/ghorbelhamdi/buddy-android.git cd buddy-android
JDK
sudo apt install openjdk-21-jdk # Debian/Ubuntu
./gradlew build -x test
./gradlew run
You need a 64-bit Android 11+ phone, plus a Claude, ChatGPT or Google account for those agents (Grok: a Google or X account). OpenCode's free models need no account.
Install blocked or "Restricted setting"? See Setup in detail.
No reports for Linux yet.
GitManual AI Agent reads the 5 key files and writes a step-by-step guide for Linux. Once written, it's saved for everyone.