MobileCLI Documentation

Complete reference for v9.9.4 — everything you can do with MobileCLI.

Getting Started

Requirements

• Android 7.0 or higher
• ~2GB free storage (bootstrap + tools)
• Any CPU architecture (ARM64 recommended)

Download & Install

1. Download the APK from mobilecli.com
2. Open the APK. Allow installation from unknown sources if prompted.
3. Launch MobileCLI. The setup wizard runs automatically.

What the Setup Wizard Installs

On first launch, MobileCLI extracts and configures:

• Linux filesystem — bash, apt, coreutils, and a full package manager
• Python 3 and Node.js — pre-installed runtimes
• 89 termux-* scripts — hardware command wrappers
• Git — version control
• Agent system skeleton — extracted from bundled archive

This takes about 5 minutes on a typical device. After setup, the terminal is ready.

First AI Session

Open the navigation drawer (swipe right or tap the menu icon). Under AI Assistants, tap the AI you want to use. Each AI opens a new terminal session. You'll need to authenticate on first use:

• Claude Code — runs claude. Authenticate with Anthropic (OAuth or API key).
• Gemini CLI — runs gemini. Authenticate with Google.
• Codex CLI — runs codex. Authenticate with OpenAI.
• OpenRouter CLI — access 100+ models via unified API key.

AI Assistants

MobileCLI ships with 4 AI coding assistants. These aren't chatbots — they're autonomous agents that read your project, write code across multiple files, run tests, and deploy.

Launch any AI from the nav drawer or type its name in the terminal.

AI Collaboration

AIs can work together through standard Unix pipes:

# Claude writes code, Gemini reviews it
claude "Write a REST API" > api.js
gemini "Review this code for bugs" < api.js

# Chain different AIs for different tasks
codex "Add unit tests" < api.js > tests.js

AI Agent System

The agent is an autonomous AI daemon that runs in the background on your phone. It monitors communication channels, processes messages through AI, and responds using your phone's native capabilities.

Starting the Agent

# From the terminal
mcli-open start

# Or use the native dashboard
# Nav drawer → AI Agent → Start

The dashboard (AIAgentActivity) provides real-time status, uptime, conversation count, and gateway indicators. Start, stop, and restart from the UI.

7 Communication Gateways

7 Skill Modules

Configuration

The agent config lives at ~/.mobilecli-open/config.json. Key settings:

{
  "ai_model": "claude-sonnet",
  "fallback_model": "gemini",
  "gateways": {
    "sms": { "enabled": true, "poll_interval": 10 },
    "telegram": { "enabled": true, "bot_token": "..." },
    "discord": { "enabled": false },
    "webhook": { "enabled": true, "port": 8780 }
  }
}

The brain supports multiple AI models. Claude Sonnet is the default. If Claude is unavailable, it falls back to Gemini automatically. The brain is channel-aware: SMS caps at 160 characters, WhatsApp allows 4,096, Discord allows 2,000.

Agent Swarm (v9.9.2)

The Agent Swarm decomposes complex goals into parallel tasks, spawns AI agents in separate terminal tabs, and coordinates their work through file-based IPC.

Commands

Architecture

• Orchestrator (Tab 0) — uses Claude CLI to decompose the goal into a JSON plan with agent assignments
• Agent tabs — each spawned via mcli-new-tab, gets its own full 200K context window
• File coordination — agents communicate through ~/.mobilecli/swarm/session-{id}/agent-N/status.md
• Status protocol — PENDING → WORKING → DONE/BLOCKED (first line of status.md)
• Mixed models — agents can use Claude, Gemini, Codex, or Cursor CLI
• Git branches — each agent works on its own branch, mcli-swarm merge combines work

AI Widget (v9.7.0)

The AI Widget is a floating WebView overlay that works while you use other apps. Chat with AI, take photos for analysis, use voice — all without leaving your current app.

Enabling the Widget

1. Open the nav drawer and tap AI Widget.
2. If prompted, grant the overlay permission (Display over other apps).
3. A floating bubble appears. Tap it to expand into the full chat.

Features

• Floating overlay — draggable bubble, expands to full chat, works over any app
• Camera + vision — take photos from the widget, AI analyzes them via base64 pipeline
• Voice mode — speech-to-text input, text-to-speech output, continuous listen-process-speak loop
• Theme support — dark and light themes, persisted in localStorage
• Settings — model selection, voice toggle, theme, all persisted
• Markdown rendering — with XSS protection and code block syntax highlighting

Bridge API

The widget communicates with native Android through window.MobileCLI, a @JavascriptInterface bridge exposed to the WebView. 17 methods are available:

// Examples of bridge methods
window.MobileCLI.sendMessage(text)
window.MobileCLI.takePhoto()
window.MobileCLI.startVoiceInput()
window.MobileCLI.stopVoiceInput()
window.MobileCLI.speak(text)
window.MobileCLI.stopSpeaking()
window.MobileCLI.getSettings()
window.MobileCLI.saveSettings(json)
window.MobileCLI.minimize()
window.MobileCLI.close()

Hot Reload (Developers)

The widget UI is TypeScript compiled with esbuild into a ~14KB bundle. During development:

• Place your source in ~/mobilecli-widget/
• Build with npx esbuild src/index.ts --bundle --outdir=dist
• The widget polls dist/version.json every 5 seconds
• When the mtime changes, the WebView reloads automatically

Load priority: ~/mobilecli-widget/dist/ (dev) takes precedence over assets/widget/ (bundled).

Voice AI

MobileCLI can answer phone calls and let callers have full conversations with AI. The AI can execute commands, control hardware, create files, and report results — all via voice.

Setup

# Interactive Twilio configuration
voice-ai setup

# You'll need:
# - Twilio Account SID
# - Twilio Auth Token
# - A Twilio phone number
# - openssh (pkg install openssh)

Commands

How Calls Work

1. voice-ai start launches an HTTP server and an SSH tunnel
2. Twilio routes incoming calls to the tunnel URL
3. Caller speaks → Twilio transcribes to text
4. Text is sent to the AI brain for processing
5. AI generates a response (and optionally executes commands)
6. Response is returned as TwiML → Twilio speaks it to the caller

The AI can do anything it can do in the terminal — create files, turn on the flashlight, check battery, open URLs, send SMS — all triggered by voice commands during a call.

Two-Tier Architecture (v9.9.0)

Voice calls use a dual brain architecture for fast, uninterrupted conversations:

• Fast tier (Haiku) — handles all conversation, responds in 1-3 seconds via direct Anthropic API
• Worker tier (Sonnet/Opus) — runs complex tasks (build games, write code, generate documents) in the background

When the AI needs to build something complex, it dispatches a worker block to a more powerful model. The caller keeps talking to Haiku while the worker runs. Results are delivered live if the caller is still on the line, or via callback/SMS if they hung up.

Worker Block Format

```worker
Build a snake game in HTML/JS. Mobile-friendly. Save to /sdcard/Download/snake.html
```

Multiple workers can run concurrently. Workers work across voice calls, SMS, and Telegram.

Config Options

Hardware Commands (65+)

Every command below is available from the terminal. All return structured JSON. All are scriptable.

Clipboard

Notifications & UI

Device Control

Battery & Network

Location

Camera

Audio & Media

Telephony & SMS

Contacts

Sensors

Biometrics

Bluetooth

IR Blaster

NFC & USB

Storage & Sharing

Development Tools

Android App Building

MobileCLI can compile and sign Android APKs on the device itself.

# One-time setup
install-dev-tools

# This installs:
# - Java 17 (openjdk-17)
# - Gradle
# - aapt2 (Android asset packaging)
# - d8 (DEX compiler)
# - apksigner

# Build an Android app
cd ~/my-app
./gradlew assembleDebug

# Copy to Downloads for user access
cp app/build/outputs/apk/debug/*.apk /sdcard/Download/

Self-Modification

MobileCLI can rebuild itself from source:

# Clone source
git clone https://github.com/MobileDevCLI/MobileCLI-v8.0.0.git ~/MobileCLI

# Make changes, rebuild
cd ~/MobileCLI
./gradlew assembleDebug

# Install the new version
cp app/build/outputs/apk/debug/app-debug.apk /sdcard/Download/MobileCLI-new.apk

MobileCLI has gone through 16+ versions built this way — AI running inside the app modifying the app's source code, compiling, and producing a new APK. On a phone.

Game Development

Godot 4 game engine is available. Build games and export to Android, iOS, Web, Windows, Mac, or Linux.

# Export to Android
godot4 --headless --export-release "Android" /sdcard/Download/game.apk

Deployment CLIs

Deploy directly from your phone:

# Vercel (websites, serverless)
vercel --prod

# Firebase (hosting, functions)
firebase deploy

# GitHub (releases with binary attachments)
gh release create v1.0.0 ./app.apk --title "v1.0.0"

# Netlify
netlify deploy --prod

# Fly.io
fly deploy

IDE Integration (v9.9.1)

Full IDE environments run on-device via proot-distro Ubuntu (needed for glibc compatibility).

Both IDEs auto-install Ubuntu via proot-distro on first run (~500MB). The proot layer provides full glibc compatibility that Termux's Bionic libc cannot.

24 Platform CLIs

File System & Paths

Support & Donations (v9.9.4)

The "Support MobileCLI" button in the nav drawer collects user feedback and offers donation via PayPal or Stripe. Donations are separate from subscriptions — they don't unlock Pro, they're just a way to support development.

How It Works

1. User fills out 3-field feedback form (what you love, what to change, what to build)
2. Feedback saves locally to ~/.mobilecli/feedback/
3. Feature requests auto-create GitHub issues tagged community-request
4. Payment method chooser: Stripe (card) or PayPal
5. Stripe donations use the create-donation-checkout Supabase Edge Function (one-time payment, not subscription)

Troubleshooting

What's Auto-Installed vs. Manual Setup

Common Issues

Setup wizard seems stuck

The bootstrap download can take 5+ minutes on slow connections. Don't close the app. If it fails, relaunch and it will resume.

/tmp permission denied

Android doesn't allow writing to /tmp. Use ~/tmp or $PREFIX/tmp instead.

Gradle downloads x86 aapt2

Add to gradle.properties:

android.aapt2FromMavenOverride=/data/data/com.termux/files/home/android-sdk/build-tools/34.0.0/aapt2

AI CLI won't authenticate

Make sure you have a valid account with the AI provider. Claude requires an Anthropic account (free tier or Claude Max). Gemini requires a Google account. Codex requires an OpenAI account.

Overlay permission for Widget

Android requires "Display over other apps" permission for floating windows. MobileCLI will prompt you and take you to the settings page. Toggle it on, then return to the app.

Voice AI calls not connecting

Ensure openssh is installed (pkg install openssh), Twilio credentials are configured (voice-ai setup), and the tunnel is active (voice-ai status).