# MobileCLI — Complete Product Documentation

> A self-hosted Rust CLI daemon that streams AI coding agents to your phone.

## What is MobileCLI?

MobileCLI is a terminal mirror and AI agent control panel for your phone. It bridges the gap between AI coding agents running on your desktop and your mobile device.

MobileCLI is NOT:
- An SSH client
- A mobile IDE or code editor
- A cloud terminal relay service
- A coding app

MobileCLI IS:
- A live terminal mirror that shows the SAME session running on your desktop
- An AI agent control panel with push notifications and tool call approvals
- A file browser for your projects (Pro feature)
- A self-hosted daemon for terminal streaming

## How It Works

1. **Install the CLI daemon** on your desktop (macOS, Linux, or Windows)
   ```
   curl -fsSL https://mobilecli.app/install.sh | bash
   ```
   Use the curl installer on macOS/Linux. On Windows, install from the GitHub Releases zip or via Cargo: `cargo install mobilecli`

2. **Pair your phone** by running `mobilecli setup` and scanning the QR code with the iOS app

3. **Start streaming** with `mobilecli claude` (or `mobilecli gemini`, `mobilecli codex`, `mobilecli opencode`)

The daemon captures PTY output from your AI coding session and streams it to your phone in real-time over WebSocket. When the AI needs approval (tool calls, file writes, etc.), MobileCLI sends a push notification through Expo; open the app to review the terminal stream and respond with controls that map to the CLI prompt.

## Architecture

- **Rust daemon** runs locally on your machine alongside your AI CLIs
- **WebSocket connection** streams terminal output to the iOS app
- **Network connection** via local network, Tailscale, or a protected endpoint you configure
- **No MobileCLI terminal relay** — terminal streams are served by your daemon
- **No account required** — just install and pair

## Supported AI CLIs

MobileCLI auto-detects the following AI coding CLIs:
- **Claude Code** by Anthropic — the most popular AI coding agent
- **Gemini CLI** by Google — Google's AI coding assistant
- **Codex** by OpenAI — OpenAI's coding agent
- **OpenCode** — Open-source AI coding tool

## Features

### Free (Forever)
- **Terminal streaming**: Real-time PTY output with full ANSI color support
- **Tool call approvals**: Numbered quick-response buttons matching CLI prompts
- **Push notifications**: Instant alerts when AI needs approval, asks questions, or finishes
- **Session management**: Multiple concurrent sessions
- **Auto-reconnect**: Seamless reconnection on flaky mobile connections
- **Smart CLI detection**: Auto-detects supported CLIs without configuration
- **Local + Tailscale**: Connect over local network or securely via Tailscale

### Pro ($20/year or $30 lifetime)
- **File browser**: Browse projects, dotfiles, and configs from your phone
- **Code editor**: Edit files with syntax highlighting for 10+ languages
- **File search**: Search by filename or within file contents
- **File operations**: Create, rename, delete, copy/paste files
- **Image & PDF viewer**: Inline viewing of images, PDFs, and hex for binary files
- **Git status**: See modified, untracked, and staged files
- **Real-time watching**: Directories update live as files change
- **Markdown preview**: Rich rendering with edit/preview toggle

Pro includes a 3-day free trial with no credit card required upfront.

## Installation

### Quick Install (macOS/Linux)
```bash
curl -fsSL https://mobilecli.app/install.sh | bash
```

### Windows
Use the GitHub Releases zip or install via Cargo.

### Via Cargo
```bash
cargo install mobilecli
```

### Mobile App
The iOS app is available on the App Store. Android is coming soon.

## Privacy & Security

- The CLI daemon runs entirely on your machine
- Sessions stay on your devices
- All code operations happen locally
- No MobileCLI terminal relay for terminal streams
- No account required
- Open source for full transparency
- Push notifications currently use Expo and include notification metadata

## Pricing

- **Free**: Core features forever (terminal streaming, approvals, notifications, sessions)
- **Pro Yearly**: $20/year with 3-day free trial
- **Pro Lifetime**: $30 one-time purchase with 3-day free trial

## FAQ

**Is MobileCLI free to use?**
Yes. The CLI daemon is open source and the core features — terminal streaming, approvals, notifications, and session management — are free forever.

**How do I connect my devices?**
MobileCLI connects your phone to your desktop daemon over WebSocket on your local network, Tailnet, or protected endpoint. The app pairs with a QR credential and completes auth-v2 challenge-response before sessions or terminal data are available. For remote access, use Tailscale so the daemon remains private to your Tailnet.

**Is my code stored on any servers?**
No. MobileCLI runs entirely on your machine. Sessions stay on your devices and all code operations happen locally.

**Where is the source code?**
The CLI daemon is open source on GitHub at github.com/MobileCLI/mobilecli. The mobile app is free but closed source due to app store requirements.

## Links

- Website: https://mobilecli.app
- GitHub: https://github.com/MobileCLI/mobilecli
- Documentation: https://mobilecli.app/docs
- Getting Started: https://mobilecli.app/docs/getting-started
- Host Mode: https://mobilecli.app/docs/host-mode
- Client Mode: https://mobilecli.app/docs/client-mode
- Troubleshooting: https://mobilecli.app/docs/troubleshooting
- Features: https://mobilecli.app/features
- Pricing: https://mobilecli.app/pricing
- Install: https://mobilecli.app/download
- Changelog: https://mobilecli.app/changelog
- Blog: https://mobilecli.app/blog
- Integrations: https://mobilecli.app/integrations
- Privacy Policy: https://mobilecli.app/privacy
- Terms of Service: https://mobilecli.app/terms
- Compare SSH+tmux: https://mobilecli.app/compare/ssh-tmux
- Compare Happy Coder: https://mobilecli.app/compare/happy-coder

## Use Cases

### Monitoring long-running Claude Code tasks while away from your desk
You kick off a large refactoring session with Claude Code — renaming modules, updating imports, running tests. Instead of sitting at your desk waiting, you walk away. MobileCLI streams the terminal output to your phone in real time. You see Claude working through files, watch test results scroll by, and get a push notification the moment the session completes or hits an error.

### Approving Gemini CLI tool calls from your phone during lunch
Gemini CLI wants to create a new file, run a shell command, or modify your codebase. MobileCLI sends a push notification that the session needs attention. You open the app, review the live terminal context, and respond with numbered quick-response buttons that map to the CLI prompts.

### Browsing and editing project files while commuting (Pro)
With the Pro file browser, you can navigate your entire project tree from your phone. Review code changes, check configuration files, read documentation, or make quick edits with syntax highlighting. The file browser supports search by filename or content, Git status indicators, and real-time directory watching.

### Managing multiple concurrent AI coding sessions
Run Claude Code on your backend project, Codex on your frontend, and OpenCode on a library — all at once. MobileCLI's session manager lets you switch between live terminal streams on your phone. Each session has independent push notifications so you know exactly which agent needs your attention.

### Getting instant push notifications when AI agents need approval or finish
MobileCLI monitors all connected AI CLI sessions and sends native iOS push notifications for tool call approval requests, questions from the agent, task completion, and errors. You never miss an important moment, even when your phone is locked or you are using another app.

### Reviewing code changes made by AI agents in real time
Watch the terminal output as your AI agent writes code, creates files, and runs tests. The full ANSI color rendering means you see syntax highlighting, diff output, and test results exactly as they appear on your desktop. Combine with the Pro file browser to immediately inspect changed files.

## Troubleshooting

### Connection issues
Check that your phone and desktop are on the same local network. If connecting remotely, ensure Tailscale is installed and running on both devices. Verify that port 9847 (the default MobileCLI port) is not blocked by a firewall. Run `mobilecli status` on your desktop to confirm the daemon is running and listening.

### CLI not detected
Ensure the AI CLI (Claude Code, Gemini CLI, Codex, or OpenCode) is installed and available in your PATH. Run `mobilecli scan` to manually trigger CLI detection. If the CLI was installed after MobileCLI, restart the daemon with `mobilecli restart`.

### Push notifications not working
Check that notifications are enabled for MobileCLI in iOS Settings > Notifications. Ensure the daemon is running and your phone can reach the desktop (try opening the app and checking the connection status). Push delivery currently goes through Expo.

### Session drops
MobileCLI includes automatic reconnection for flaky mobile connections. If sessions drop frequently, check your network stability. On cellular connections, brief drops are normal and MobileCLI will reconnect automatically. For persistent issues, try connecting via Tailscale instead of local WiFi.

### File browser not working
The file browser is a Pro feature and requires an active subscription or trial. Check your subscription status in the iOS app under Settings. If you are on a trial, verify it has not expired. The file browser requires a WebSocket connection to the daemon — ensure the daemon is running.

## Comparison: MobileCLI vs SSH + tmux

| Feature | MobileCLI | SSH + tmux |
|---------|-----------|------------|
| Push Notifications | Yes, native iOS | No |
| Approval UX | Numbered buttons | Raw terminal input |
| Setup Time | ~30 seconds | 15-30 minutes |
| Reconnection | Automatic | Manual reattach |
| File Browsing | Built-in (Pro) | Requires separate tools |
| Security Model | Auth-v2 pairing plus trusted LAN/Tailscale | SSH keys + port forwarding |
| Cost | Free core, $20/yr Pro | Free |
| CLI Detection | Automatic | Manual |
| Mobile Optimized | Yes, native iOS app | No, terminal in browser or SSH app |
| ANSI Color Support | Full rendering | Depends on SSH client |

MobileCLI is purpose-built for monitoring AI coding agents on your phone. SSH+tmux is a general-purpose remote terminal solution. MobileCLI provides a native mobile experience with push notifications, quick-action buttons, and automatic CLI detection. SSH+tmux requires manual configuration, has no push notification support, and presents a raw terminal interface that is difficult to use on small screens.

## Comparison: MobileCLI vs Happy Coder

| Feature | MobileCLI | Happy Coder |
|---------|-----------|-------------|
| Hosting | Self-hosted | Cloud |
| Supported CLIs | Claude Code, Gemini, Codex, OpenCode | Claude Code only |
| Interface | Terminal mirror | Chat-like |
| Open Source | CLI is open source | Closed source |
| Push Notifications | Yes | Yes |
| File Access | Pro feature | No |
| Account Required | No | Yes |
| Price | Free core, $20/yr Pro | Monthly subscription |
| Data Privacy | Terminal stream avoids MobileCLI relay; Expo handles notification metadata | Data passes through cloud |
| Multi-Session | Yes | Limited |

MobileCLI is a local-daemon tool and supports multiple AI coding CLIs. Your terminal stream is not routed through MobileCLI servers. Happy Coder is a cloud-based service focused on Claude Code with a chat-like interface. If you value local terminal streaming, multi-CLI support, and open source, MobileCLI may be the better fit. If you prefer a managed cloud service and only use Claude Code, Happy Coder may be simpler to set up.

## Extended FAQ

**What is MobileCLI?**
MobileCLI is a self-hosted Rust daemon that streams AI coding agent sessions (Claude Code, Gemini CLI, Codex, OpenCode) to your phone. It lets you monitor terminal output, approve tool calls, browse files, and get push notifications — all from a native iOS app.

**Is MobileCLI free?**
Yes. The core features — terminal streaming, tool call approvals, push notifications, and session management — are free forever. Pro features (file browser, editor, search) cost $20/year or $30 lifetime.

**Does MobileCLI work with Claude Code?**
Yes. MobileCLI supports Claude Code, Gemini CLI, Codex, and OpenCode. It auto-detects supported CLIs without any configuration.

**Is my code stored in the cloud?**
No. MobileCLI does not store your code or terminal stream on MobileCLI servers. The daemon runs on your machine and serves terminal streams over your configured network path. Push notifications currently use Expo and include notification metadata.

**How does MobileCLI connect to my phone?**
MobileCLI connects your phone to your desktop daemon over WebSocket on your local network, Tailnet, or protected endpoint. The app pairs with a QR credential and completes auth-v2 challenge-response before sessions or terminal data are available. For remote access outside your home or office, use Tailscale so the daemon is only reachable by devices in your Tailnet.

**What platforms does MobileCLI support?**
The CLI daemon runs on macOS (Apple Silicon + Intel), Linux (x86_64 + ARM), and Windows (x64). Use the curl installer on macOS/Linux; on Windows use the GitHub Releases zip or Cargo. The mobile app is available for iOS on the App Store. Android support is coming soon.

**Can I use MobileCLI without Tailscale?**
Yes. MobileCLI works over your local network by default. Tailscale is only needed if you want to connect when your phone and desktop are on different networks (for example, monitoring from outside your home or office).

**Does MobileCLI modify my AI coding CLI?**
No. MobileCLI monitors the PTY (pseudo-terminal) output without modifying the CLI itself. Your AI coding tool runs exactly as it normally would — MobileCLI simply captures and streams the terminal output and provides a way to send input back.

**What terminal features are supported?**
MobileCLI supports full ANSI color rendering, text formatting (bold, italic, underline), escape codes, and cursor positioning. The terminal output on your phone looks the same as it does on your desktop.

**How does the file browser work?**
The file browser is a Pro feature. It serves your project filesystem over the existing WebSocket connection between the daemon and the iOS app. You can browse directories, open files with syntax highlighting, search by filename or content, create and edit files, and view images and PDFs. Directories update in real time as files change on disk.

**Is the mobile app free?**
Yes. The MobileCLI iOS app is free to download and use. Core features (terminal streaming, approvals, notifications, sessions) work without any purchase. Pro features (file browser, editor, search) require an in-app purchase ($20/year or $30 lifetime) with a 3-day free trial.

**Can I use MobileCLI on Android?**
Android support is coming soon. Currently, MobileCLI is available for iOS only on the App Store. The CLI daemon already runs on macOS, Linux, and Windows — the Android app is in development.

## Technical Specs

- **Default port**: 9847
- **Protocol**: WebSocket (`ws://` on local/Tailscale networks, `wss://` when you configure a TLS endpoint)
- **Supported desktop OS**: macOS (Apple Silicon + Intel), Linux (x86_64 + ARM), Windows (x64)
- **Supported mobile OS**: iOS 15+, Android 8+ (coming soon)
- **Language**: Rust (CLI daemon), React Native/TypeScript (mobile app)
- **Install methods**: curl script, Cargo
- **System requirements**: Any system that can run Rust binaries
- **Network**: Local network or Tailscale mesh VPN
- **Terminal rendering**: Full ANSI color, formatting, escape codes, cursor positioning
- **Connection model**: Local daemon over configured network path, no MobileCLI terminal relay
- **Authentication**: Auth-v2 QR pairing with challenge-response proof before sessions, terminal data, filesystem data, or push-token registration