A real AI agent on your own phone — including the one in your drawer.
Website · Changelog · Roadmap · Contributing · Code of Conduct
-3DDC84){kind=icon}
An on-device AI agent — a full Alpine Linux shell, browser automation, and device integrations, running on the phone.
What this fork is for: one phone, yours, working on its own. Upstream's agent answers when you talk to it. This one also acts when you don't — it wakes on the notifications you choose and handles them while you are away.
Two things that follow, which upstream does not target:
- The spare phone in your drawer can run it. Upstream crashes on startup on Android 8 and 9; that is fixed here, so a Galaxy Note8-era handset works as a dedicated agent instead of being e-waste.
- It answers in the messenger the message came from. The agent replies through the notification's own quick-reply action, so KakaoTalk, SMS, LINE or Telegram becomes a two-way channel to it — no per-app integration.
You bring the model: your own API key, or a plain account sign-in — the app ships OAuth for Claude, OpenAI, Gemini, xAI, Kimi, OpenRouter and Antigravity, so a subscription you already pay for can drive it without per-token billing.
Verified running on Galaxy Note8 hardware (Android 9, API 28) — see
Android 8 and 9 support. If you end up with more
than one phone, tools/openthumb-fleet drives them from a
laptop; it is a development aid, not what the app is for.
Start here — What this fork is for · Notification triggers · Android 8 and 9 support · Building from source
The app — What it does · What you can do with it · Skills · The app itself
Running more than one — The fleet tool · Optional sync
Everything else — Press · Beta programme · Repository layout · Acknowledgements · License · Community
Nearly all of the code here was written by the OpenMinis authors, not by us. If you want one great agent on your own phone — better documented, actively released, on the App Store — use OpenMinis. It is the better choice for almost everyone.
OpenThumb exists for one case upstream does not aim at: a fleet of Android devices driven from a single host. Everything below marked fork is ours; everything else is upstream's work under GPL-3.0, with copyright notices unmodified.
| fork | Notification triggers — the agent wakes on the notifications you choose and handles them, unattended |
| fork | tools/openthumb-fleet — multi-device orchestration over the built-in JSON-RPC server |
| fork | Android 8/9 startup crash fix |
| fork | Replies in the messenger the notification came from — KakaoTalk, SMS, LINE, Telegram |
| fork | CI that builds debug and release APKs and runs this fork's unit tests (upstream has none) |
| fork | scripts/rebrand.sh — reproducible package rename, JNI symbols included |
| fork | Privacy policy (nothing collected) · distribution channels |
Upstream's agent answers when you talk to it, and its scheduled tasks fire on a clock. Neither covers "something happened, deal with it." A trigger rule is an app package plus a text match plus a prompt; when a matching notification arrives, the agent runs headlessly on the same path scheduled tasks use — so it inherits the foreground service, session handling and completion notice for free.
Rules live in Scheduled tasks → the bell icon. Five gates keep it from running away: the app ignores its own notifications (a self-trigger loop would never stop), ongoing and group-summary notifications are skipped, global quiet hours suspend everything overnight, each rule has an optional active window plus a cooldown claimed before dispatch so a burst cannot double-fire it, and no more than two trigger runs are ever in flight.
Every firing lands in a run history (the clock icon on the rules screen) — the counterpart to scheduled tasks' run records — and the rule editor has a Test button that fires the prompt immediately with a synthetic notification, so a rule can be proven before it is armed.
Requires Notification access, which Android only grants by hand — the rules screen links straight to that settings page.
Recipes → — ready-made rules for replying in KakaoTalk or SMS, filing delivery alerts, and turning bank notifications into a ledger.
A lab utility, not the product. OpenThumb is an app for one person's phone; this is here because developing for that phone is easier when you can drive several at once from a laptop, and because debug builds already expose the server that makes it possible. Skip this section if you have one phone.
Every debug build already serves JSON-RPC on device-local 127.0.0.1:5321 —
that is upstream's work, and it is the whole reason this fork is small. The
port is unreachable from the host, so openthumb-fleet forwards one host port
per device via adb and fans calls out across all of them.
tools/openthumb-fleet devices # attached devices that have the app
tools/openthumb-fleet status # android/sdk/sandbox per device
tools/openthumb-fleet health # rpc reachability + battery per device
tools/openthumb-fleet prompt "..." # same prompt to every agent, concurrently
tools/openthumb-fleet run "..." # prompt and wait; one result JSON per device
tools/openthumb-fleet collect <sid> # poll every device until a session stops
tools/openthumb-fleet enqueue "..." # queue a job for later
tools/openthumb-fleet jobs # list the queue
tools/openthumb-fleet drain # run queued jobs one at a time
tools/openthumb-fleet call <method> # any RPC method, fleet-wide
tools/openthumb-fleet cancel # stop in-flight runsrun and drain collect results into ~/.openthumb/fleet/results/ (one
<jobId>-<serial>.json per device, including failure statuses), so an
overnight batch leaves an auditable trail instead of scrollback. The queue
lives beside it as plain JSONL — jobs that fail to reach the fleet are
re-queued, results are never lost silently.
call takes any method the app exposes — ask a device for the list with
call rpc.discover. Dependencies: adb, curl, python3. No install step,
no daemon, no config file.
Two things worth knowing before you rely on it:
- Debug builds only. Release builds ship no debug server, by design. A fleet is a lab, not a product surface.
- Every call needs the device token (since 1.0.4), loopback included — an
app installed on the phone can reach
127.0.0.1too, and this RPC exposes stored API keys.openthumb-fleetreads each device's token withrun-asand sends it for you; that is the privilege adb has and another app does not. Read it by hand withadb shell run-as com.fug.openthumb cat files/debug_server_token.
Upstream declares minSdk = 26 (Android 8) but crashes at startup on anything
below Android 10:
java.lang.NoSuchMethodError: No static method isExternalStorageLegacy()Z
at com.openminis.app.MinisApp.onCreate
Environment.isExternalStorageLegacy() is API 29, called unguarded on the
pre-R branch of a diagnostic helper — so every API 26–28 device dies in
Application.onCreate. One version guard fixes it. We audited the rest of the
tree for the same class of bug and found no other unguarded API 29+ call.
This is exactly what CI is for, which is why this fork has some: upstream runs
no lint, so NewApi never fired.
Fixed and verified on a Galaxy Note8 (Android 9, API 28) — sandbox boots, shell
runs, no UnsatisfiedLinkError. Contributed upstream as a verified patch on
OpenMinis#118 (a user's
report of the same crash); upstream is a release mirror and does not take pull
requests.
OpenThumb has no server and no accounts, and that does not change. If you want
your trigger rules, trigger run history and scheduled tasks replicated to a
second device, tools/sync-worker/ is a Cloudflare Worker you deploy to your
own Cloudflare account (D1 + R2, free tier covers personal use) — the app
points at your URL with a bearer token you generate. Nobody else operates it;
the worker keeps no analytics and never logs payload contents.
Sync is disabled until you enter an endpoint and token in Settings → Sync.
v1 pushes rules, run history and scheduled tasks; chat and two-way merge are
deliberately later. See tools/sync-worker/README.md for the 8-step deploy.
Everything from here down describes the app OpenThumb inherits, adapted from the upstream OpenMinis README — their work, their words, lightly edited where paths differ in this fork.
Your private, on-device AI agent.
OpenMinis brings leading models — Claude, GPT, Gemini and more — into a native mobile experience, and gives them a real computer to work with: a full Linux shell running on your device, browser automation, extensible skills, persistent memory, and deep system integration.
It is free, and fully open source.
We believe that in the age of AI, technical design and code are no longer where a product's advantage lies. The best agent emerges from a tight feedback loop with the people who use it — their expectations and their reports are what converge on the product.
Official website: openminis.app
| Bring your own model | Claude, GPT, Gemini and other providers, via your own API keys or account sign-in. |
| A real Linux shell | A sandboxed Alpine Linux environment runs on-device — the agent can install packages, run scripts, and work with real files. |
| Device integration | Health, Calendar, Reminders, Contacts, HomeKit, Bluetooth, Clipboard, Media, Alarms and more, exposed to the agent as tools. |
| Browser automation | The agent can browse and interact with the web on your behalf. |
| Skills & memory | Extensible skills plus persistent memory across sessions. |
| Workspaces | Organise work into separate contexts, addressable via minis://workspace/. |
| Native offloads | Heavy or platform-specific work is handed to native code instead of the sandbox. |
A few things people actually use it for:
- Photograph a meal, log the nutrition — Minis identifies the dishes, estimates calories and macros, and writes them to Apple Health.
- Wake up to your timeline — Shortcuts triggers Minis to fetch your X timeline, summarise it, synthesise speech, and play it as your alarm.
- Turn group chatter into tasks — pull messages from a Telegram group, extract bugs and action items, deduplicate them, and file them into Apple Reminders.
- Mount your Obsidian vault — research, clean up and write Markdown notes back into the vault as a normal workspace.
- Share anything into a calendar event — send a page or message to Minis via the iOS Share Sheet and it creates the event, time and place included.
→ OpenMinis/AwesomeMinis — a curated, community-contributed collection of use cases and workflows across health, productivity, research, finance and developer tooling.
A skill is a folder with a SKILL.md file — instructions, and optionally scripts,
references and assets — that the agent loads on demand when a request matches it.
Metadata stays in context for triggering; the body and bundled resources load only
when the skill is actually used.
Minis has its own tool system, but it does not require skills written specifically for it: skills built for Claude, Codex, OpenClaw or Hermes Agent generally run in Minis as-is. Skills that have been adapted to Minis' tools simply run better — they can reach the Linux shell, device integrations and native offloads directly.
→ OpenMinis/MinisSkills — skills adapted for Minis alongside ones built for it from scratch, covering TTS, search, media downloads, health analysis, cloud APIs and more.
"the most impressive indie app I've seen in a while"
— Federico Viticci, Open Minis Is the iOS Agent I Wish Siri AI Could Be, MacStories (July 2026)
"在很大程度上实现甚至局部超越了 Apple Intelligence"
— Ye Han, 这可能是 iPhone 最强 Agent 软件，没有之一 丨Open Minis 入门指南, 知乎 / Zhihu (June 2026)
"可能是 iOS 端最强 AI Agent"
— Open Minis：可能是 iOS 端最强 AI Agent, 小众软件 / Appinn (March 2026)
App Store releases can lag behind: every update waits on review, and we hold builds back when stability warrants it. The TestFlight build is where fixes and new features land first.
On Android, the releases page always carries the latest APK.
Minis ships a Linux sandbox inside the app, so the native dependencies (iSH on iOS, PRoot on Android, FFmpeg, LAME) and the Alpine rootfs are built from source rather than committed as binaries.
→ See BUILDING.md for the full first-build guide.
The short version:
git clone --recurse-submodules https://github.com/neulketing/openthumb.git
cd openthumb
# iOS — order matters: FFmpeg links against LAME
./deps/build_lame.sh && ./deps/build_ffmpeg.sh
./deps/build_ish.sh && ./deps/prepare_alpine_rootfs.sh
open src/ios/Minis.xcodeproj
# Android — needs NDK r28+
./deps/build_proot.sh && ./scripts/prepare_android_sandbox.sh
cd src/android && ./gradlew :app:assembleDebugBUILDING.md covers the toolchain requirements per platform, the build-time
customization templates, and a troubleshooting section for the failure modes
you are most likely to hit.
src/ios/ iOS app (Swift / SwiftUI) + share, widget and file-provider extensions
src/android/ Android app (Kotlin / Compose) + JNI native code
src/shared/ Assets shared by both platforms
deps/ Native dependency build scripts and vendored sources
docs/specs/ Architecture and interface specifications
scripts/ Rootfs preparation and developer tooling
OpenMinis stands on a great deal of open-source work. Our thanks to the maintainers of these projects — the full inventory, with versions and license terms, is in THIRD_PARTY_LICENSES.md.
The sandbox — the heart of the product:
- iSH (GPLv3) — Linux usermode emulation on iOS. We run an ARM64 fork.
- PRoot (GPLv2) — user-space chroot for the Android sandbox, via our fork; talloc (LGPLv3+) underpins it.
- Alpine Linux — the minirootfs the sandbox boots.
Media & text — FFmpeg (LGPL-2.1+), LAME (LGPL), cppjieba (MIT), KaTeX (MIT).
iOS — SwiftAnthropic, SwiftMath, RealTimeCutVADLibrary (all MIT), swift-cmark (BSD-2-Clause), and the Apple / Swift Server Workgroup packages (Apache-2.0).
Android — AndroidX & Jetpack Compose, OkHttp, Coil, kotlinx serialization & coroutines, multiplatform-markdown-renderer, Reorderable, ACRA (all Apache-2.0), and Shizuku (MIT).
OpenMinis is licensed under the GNU General Public License v3.0.
The app links GPL-licensed components — iSH (GPLv3) and PRoot (GPLv2) — so the combined work is distributed under GPLv3. Bundled third-party licenses are listed in THIRD_PARTY_LICENSES.md.
- Telegram: Join the group
- Issues: Bug reports, feature requests and discussion via GitHub Issues
This repository is a mirror of a private development tree, so it does not accept pull requests — there is nowhere for them to land. Issues are the way to shape the product, and AwesomeMinis and MinisSkills both do take contributions. See CONTRIBUTING.md.