Skip to content

Your phone, on your command. Gotcha is world's first fully on-device AI copilot for Android that turns natural language into real device actions — safely.

README

📱 Gotcha

Say it. Gotcha does it.

The world's first open-source AI copilot for Android — fully on-device, turning natural language into real device actions.

Website Docs Discord Release License

Android 11+ · Bring your own model · No PC, no server, no ADB tether


Most AI assistants talk — Gotcha acts. 🤖

Say "text mom I'm running late", "free up some space", or "what's on my screen?". An LLM reads your request plus live device context, picks from 100+ purpose-built Android tools, executes real actions, and reports back — by text or by voice. 🗣️

Everything runs in one self-contained app on your phone. Bring your own API key (OpenAI, OpenRouter, Groq, or a local llama.cpp / LM Studio / Ollama server) — it's encrypted on-device and never synced — or sign in to Samosa AI and skip the key entirely. 🔑

🏁 Getting Started

Grab the latest .apk from GitHub Releases, then follow the Getting Started Guide — or watch the video walkthrough above. 🛠️

Once installed, Gotcha tells you when a new version is out. About twice a day it downloads update.json from GitHub; the request carries no account or device identifier, though GitHub sees your IP address as with any download. Tapping the notification opens Settings ▸ About, which downloads the APK, checks its SHA-256 and hands it to Android's installer. Turn it off under Settings ▸ Notifications ▸ App updates.

Building from source instead? 👇

./gradlew installDebug

The app opens on Settings — fill in API key, Base URL (including /v1/), and Model name, grant the prompted permissions, and you're live. Full setup notes live in RUNNING.md.

🌟 Highlights

  • 🧰 100+ device-control tools — calls, SMS, contacts, calendar, alarms, files, terminal, location, apps, clipboard, camera, screen automation, notifications, device admin, and root. → Tool Catalog
  • 🎭 Two copilot modes — read-only Monitor (inspect & plan, 30 tools) and full-access Operator (execute & automate). Switch any time, even mid-conversation. → Copilot Modes
  • 🔮 The Assistive Ball — a floating bubble that rides over every app, hosting push-to-talk voice calls with the full copilot. → Assistive Ball
  • 🔍 Screen Lens & Companion — circle anything on screen to copy, translate, or ask about it; get one-tap offers when an address, price, or date appears. Text extraction runs on-device.
  • 🛡️ Safety by design — capability tiers, up-front permissions, a hard confirmation gate on sensitive actions, a command deny-list, and an append-only audit log. → Safety & Permissions
  • 🏠 Local & cloud AI — any OpenAI-compatible /chat/completions endpoint with tool calling, or Samosa AI for free starter credits.
  • ⚡ Skills — bundled operational guidance for specific apps, injected automatically when that app is in front. → Skill Hub
  • 🎙️ Voice & vision — selectable TTS/STT providers, plus screenshot understanding for multimodal models.

🐧 Termux (Linux shell)

Termux (the F-Droid or GitHub build) gives Gotcha a real Linux user-space on Android and is reached through the run_termux_command tool, which runs headlessly under Termux's user id. It is genuinely useful for package installs, scripts, compilers, Python, git, and the rest of the long Unix tail — but it is not a server. There is no root, no systemd, no kernel access, and no persistence between shell calls. Long-running processes must be backgrounded explicitly; large packages may need a mirror change on slow networks. The bundled termux_* skills (termux_operations, termux_repositories, termux_filesystem, termux_background, termux_proot) enumerate the realistic limits; ask the assistant to search_skills for termux_operations if anything is unclear. See docs/termux-setup.md for the one-time setup walkthrough.

📚 Documentation

🧪 Beta Testers

Thanks to the people who try Gotcha builds before release and tell us what breaks:

🤝 Project & Community

  • 💬 Discord — chat with the team and other users, share skills, and get help in real time.
  • 🗣️ GitHub Discussions — feature ideas, Q&A, and longer-form conversations that outlive a chat message.
  • 💡 Contributing — branching strategy, how to add a tool, and the checks to run before a PR:
    ./gradlew testDebugUnitTest    # JVM unit tests (needs a POSIX sh)
    ./gradlew detekt lintDebug     # static analysis — no baselines, everything must pass
    
  • 🛡️ Security Policy — how we handle vulnerabilities and where to report them privately.
  • ⚖️ License — released under AGPL-3.0. Copyright © 2026 Samosa AI.

[!WARNING] Use Gotcha responsibly and at your own risk. It is driven by LLMs acting autonomously across powerful Android APIs. Models can hallucinate, misread instructions, or fire unexpected tool calls — which can mean data loss or unwanted configuration changes. Start in Monitor mode, prefer a spare device or emulator while evaluating, grant permissions carefully, and keep backups. We assume no liability for any loss or damage incurred through use of Gotcha.