MobileClaude Agent

Desktop agent for MobileIDE — control Claude Code from your iPhone via Supabase Realtime.

Requirements

• Node.js 18+
• Claude Code CLI installed and accessible in PATH
• A Supabase project with the schema applied

Installation

npm install -g mobileclaude-agent

Or run locally from this directory:

npm install
npm run build

Setup

1. Apply Supabase Migrations

In your Supabase project → SQL Editor, run in order:

1. ../supabase/migrations/001_initial_schema.sql
2. ../supabase/migrations/002_realtime.sql

Also enable Realtime in Supabase Dashboard → Database → Replication for: prompts, results, agent_status, session_metas

2. Configure the Agent

mobileclaude-agent --setup

You'll be prompted for:

• Supabase Project URL — from Project Settings → API
• Supabase Anon Key — public key, safe to share
• Supabase Service Role Key — secret key, stored with chmod 600
• Your account email + password — for initial authentication

Config is saved to ~/.mobileclaude/config.json (chmod 600).

3. Start the Agent

mobileclaude-agent

The agent will:

1. Connect to Supabase and restore your session
2. Start watching ~/.claude/projects/ for Claude Code sessions
3. Subscribe to new prompts from your iPhone
4. Send heartbeats every 30s so the iOS app knows you're online

How It Works

iPhone (iOS App)
  → INSERT prompt into Supabase `prompts` table (status=pending)

Desktop Agent
  → Receives prompt via Supabase Realtime
  → Checks freemium quota (1 prompt/day free)
  → Spawns: claude --print --dangerously-skip-permissions --output-format stream-json
  → Streams output to `results` table every ~500 bytes
  → iOS app receives live updates via Realtime

On completion:
  → status=done, session_id saved back to prompts table
  → iOS can send follow-up prompts with --resume

Session Indexing

The agent watches ~/.claude/projects/**/*.jsonl and syncs all Claude Code sessions (including those started in the terminal) to Supabase. This makes them visible in the iOS app's session list — tap any session to continue it from your iPhone.

Freemium Model

• Free tier: 1 prompt per day
• Premium: Unlimited (set by iOS app after StoreKit purchase)

The freemium gate is enforced server-side via the check_and_increment_daily_usage PostgreSQL function, using the service role key. The iOS app cannot forge its own count.

Development

npm run dev         # Run with tsx (no build step)
npm run test:types  # TypeScript type check
npm test            # Run Jest unit tests
npm run build       # Compile to dist/

Autostart

The agent will prompt you to enable autostart during setup. This uses:

• macOS: LaunchAgent plist (~/Library/LaunchAgents/)
• Windows: Registry run key (via node-auto-launch)
• Linux: XDG autostart entry (~/.config/autostart/)

System Tray

On desktop systems with a GUI, a system tray icon shows agent status. On headless servers, the agent runs without a tray (no error, just a log message).

Security Notes

• The service role key bypasses Supabase RLS — keep it secret
• ~/.mobileclaude/config.json is chmod 600 — only your user can read it
• --dangerously-skip-permissions is required for unattended claude CLI execution
• The freemium gate uses SECURITY DEFINER PostgreSQL function to prevent tampering