PhoneClaw Mobile Runtime
Turn an iPhone into a local AI runtime with native mobile actions.
- Source repo
- kellyvv/PhoneClaw
- Stars
- ★ 1.3k
- Last updated
- 3mo ago
- License
- Apache-2.0
- Primary language
- Swift
- FA score
- 43/100 · Major gaps
At a glance
- How it runs
- Works with
- Platform-specificCodex (Partial support)
- Cost
- Free, no paid service needed
- Setup effort
- High · needs real infrastructure
- You'll need
- Typical use
- An iPhone user organizing a personal schedule can create events in natural language, inspect today's or this week's calendar, and ask for busy-time analysis.
- Not a fit if
- Users without an iPhone device and a macOS + Xcode setup
- Teams needing Android, Windows, or desktop runtimes
- Older iPhones or Sideloadly-signed installs with tight memory limits
- Source review
- 43/100 · Major gaps 2 safety controls not found
What does this agent do, and when should you use it?
PhoneClaw is a local AI agent runtime for iPhone that combines on-device inference with native mobile Skills. It runs Gemma 4 E2B/E4B through LiteRT and offers MiniCPM-V 4.6 for image Q&A and LIVE camera recognition. Requests can enter through text, voice, images, LIVE, or LiveLand, then use calendar, reminders, contacts, clipboard, and HealthKit capabilities. Skills are defined as SKILL.md files, with device tools registered through ToolRegistry.swift and Tools/Handlers. For heavier inference, a paired Mac can run PhoneClaw Gateway and expose Ollama, Codex CLI, or Antigravity CLI as a LAN inference source.
A user submits a request through chat, voice, an image, LIVE, or LiveLand; PhoneClaw processes it with local Gemma 4 or MiniCPM-V 4.6 and follows the Skill type. For a device Skill, the model emits <tool_call> and invokes an iOS tool registered in Tools/ToolRegistry.swift and Tools/Handlers/<Name>.swift; documented operations include creating and reading calendar events, availability analysis, creating reminders, managing contacts, reading and writing the clipboard, and reading HealthKit metrics. A content Skill such as translate produces a response from its SKILL.md instructions, while a network Skill such as web-search invokes network tools only for an explicit request for live information, search, or URL reading. Results are returned in the app interface, while LiveLand also shows task stages such as understanding, executing, and completion. In remote mode, the current inference request is sent to the paired Mac gateway, which listens on port 18080 by default and advertises _phoneclaw-llm._tcp through Bonjour.
- An iPhone user organizing a personal schedule can create events in natural language, inspect today's or this week's calendar, and ask for busy-time analysis.
- A person who wants an on-device health summary can authorize HealthKit and query steps, distance, active energy, heart rate, sleep, workouts, weight, or heart-rate variability.
- Someone updating personal contacts can ask the app to find, save, change, or delete contacts, with phone-number deduplication.
- A user who needs visual assistance can ask questions about a camera or photo-library image, or use LIVE mode for real-time camera recognition.
- A user with a Mac on the same LAN can move inference off the phone by pairing PhoneClaw Gateway and selecting an Ollama, Codex CLI, or Antigravity CLI source.
How do you install or deploy this agent?
The recommended route is TestFlight: https://testflight.apple.com/join/YuUSwq78 . After installation, download a model in Model Settings and enable the permissions needed by Skills. Building from source requires macOS, Xcode 16, iOS 17+, CocoaPods, a physical device, and an Apple ID: run git clone https://github.com/kellyvv/phoneclaw.git, cd phoneclaw, and pod install, then open the workspace with open PhoneClaw.xcworkspace. In the PhoneClaw target, select a Team and replace the Bundle Identifier with your own unique value before running on the connected iPhone. With a shell install, download E2B or E4B in Model Settings; alternatively, package a .litertlm model as an app resource.
How do you use this agent?
Download or select a model in Model Settings, then grant the calendar, reminders, contacts, or health permissions your intended Skills need. Use the puzzle icon to manage Skills and the slider icon for model settings, system prompts, and permissions; then issue a request such as “Remind me to send the file at 8 tonight” or “What is on my calendar today?” For Mac inference, launch PhoneClawGateway.app, allow macOS local-network access, and choose Ollama, Codex CLI, or Antigravity CLI in Gateway. Put the iPhone and Mac on the same LAN, pair the Mac under “Mac Remote Inference,” and choose the remote model.
What are this agent's strengths and limitations?
- Combines LiteRT local models with iOS-native calendar, contacts, reminders, clipboard, and HealthKit actions in one mobile runtime.
- Uses file-based SKILL.md definitions and validates allowed-tools against ToolRegistry registrations.
- Supports text, voice, image, LIVE, and LiveLand interaction modes; MiniCPM-V 4.6 covers image Q&A and live camera recognition.
- The optional Mac Gateway uses Bonjour discovery and pairing while retaining the iPhone Skill experience and offering several documented runtime sources.
- Model management includes cancellation, resumable downloads, retries, model switching, cache clearing, and history trimming for mobile constraints.
- Its core deployment target is an iOS 17+ physical device; source builds additionally require macOS, Xcode 16, CocoaPods, and an Apple ID, with no documented runtime for other desktop or mobile platforms.
- E2B is about 2.4 GB and E4B about 3.4 GB; E4B and complex multi-turn tasks are recommended for newer iPhones, so memory and hardware affect adoption.
- Calendar, reminders, contacts, and HealthKit depend on user permissions; previously denied access must be re-enabled in iOS Settings.
- Web search, URL reading, and Mac inference are not fully local paths; when the Mac uses a CLI or another upstream provider, its data handling governs that request.
- Licensing evidence is inconsistent: the repository metadata says NOASSERTION while the README claims Apache 2.0, so adopters should verify licensing before use.
How does this agent compare with similar options?
Remote inference is not tied to a single backend: PhoneClaw Gateway can select Ollama, Codex CLI, or Antigravity CLI. The documented Ollama path keeps inference on the Mac; CLI and other upstream-provider paths follow the selected provider's data practices.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| PhoneClaw Mobile Runtime This agent | 43 · Major gaps | Desktop appFree | ★ 1.3k | 3mo ago | Swift | — |
| Conduit | 73 · Some gaps | Desktop appFree + model costs | ★ 2.4k | today | Dart | OpenAI API |
| Grux for Mac | 67 · Some gaps | Desktop appFree | ★ 31 | 5d ago | Swift | Claude API |
| DeepChat | 66 · Some gaps | Desktop appFree + model costs | ★ 6.4k | today | TypeScript | OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: README explicitly states local processing by default, web search, webpage reading, and Mac remote inference are explicit user-triggered; Mac remote inference requires explicit pairing and model selection; deletions and bulk operations request confirmation. However, permission management details (e.g., least privilege) are not reflected in source, dependency security (e.g., vulnerability scanning) is not mentioned, and rollback mechanisms are not described. Deductions: insufficient evidence for least privilege, dependency security, and rollback.
README describes a consistent architecture and features, but no test results or execution evidence are provided. For dependency availability, model downloads rely on Hugging Face and ModelScope, but mirror availability is not stated. For failure messages, FAQ provides some troubleshooting, but not systematic. Deductions: insufficient evidence for dependency availability and failure messages.
README clearly identifies target audience (iOS developers, general users) and use cases (local AI assistant, health data, calendar, etc.), and explains capability boundaries (e.g., device model limits, memory limits). For trigger precision, the skill system has trigger words, but how to avoid false triggers is not explained. For environment fit, iOS version, Xcode version, etc. are specified. Deductions: insufficient evidence for trigger precision.
README provides clear information architecture (table of contents, features, quick start, etc.), detailed installation notes (TestFlight, source build, model download), stable naming (version numbers, model names), rich examples and FAQ, Apache-2.0 license, and changelog with version history. However, known limitations are not explicitly listed, and maintenance responsibility is not clear (no contribution guide or maintainer mentioned). Deductions: insufficient evidence for known limitations and maintenance responsibility.
For output usability, README shows practical usage examples and a demo video, but no output quality assessment. For marginal value, the local AI agent framework is innovative, but not compared with existing solutions. For cost-benefit, no performance benchmarks or resource consumption data are provided. Deductions: insufficient evidence for cost-benefit.
Claims in README (e.g., performance improvements, features) lack verifiable test data or references. Cross-source corroboration is insufficient because only README and a few files are available. For fact-inference separation, README distinguishes factual descriptions and speculation (e.g., 'may'), but not explicitly. Deductions: insufficient evidence for claim traceability and cross-source corroboration.
- Not found in source: dependency securityPin versions and run a dependency audit (npm audit, pip-audit) before installing; prefer running it in a container.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- Dependency security is not mentioned; check third-party libraries for vulnerabilities.
- Rollback mechanism is not described; model or skill updates may not be reversible.
- Permission management details are not reflected in source; review actual permission requests.
- Claims (e.g., performance improvements) lack verifiable data.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
mac-gateway-v0.1.1 PhoneClaw Gateway for Mac v0.1.1
Release notes excerpt
Fixes a startup crash in PhoneClaw Gateway caused by missing SwiftPM resource bundle lookup for the app icon. Downloads: - Apple Silicon Mac: PhoneClawGateway-macOS-v0.1.1.zip - Intel Mac: PhoneClawGateway-macOS-x86_64-v0.1.1.zip Changes: - Avoids crashing when the SwiftPM resource bundle is unavailable at launch. - Packages the generated SwiftPM resource bundle into PhoneClawGateway.app. - Updates README download links to v0.1.1. Validation: - Built with PhoneClawGateway/build-app.sh for Apple Silicon. - Built with swift build -c release --arch x86_64 for Intel. …View on GitHub ↗ -
mac-gateway-v0.1.0 PhoneClaw Gateway for Mac v0.1.0
Release notes excerpt
PhoneClaw Gateway is the macOS client for using a Mac as a remote inference source for PhoneClaw on the phone. What's included - macOS Gateway app with a normal Dock window and menu bar entry - Bonjour LAN discovery service: _phoneclaw-llm._tcp - iPhone pairing approval flow - Runtime sources: Ollama, Codex CLI, and Antigravity CLI - Local Network permission metadata for macOS Requirements - macOS 14 or later - Apple Silicon Mac - iPhone and Mac on the same LAN - PhoneClaw iPhone build with Mac Remote support Quick start 1. Download PhoneClawGateway-macOS-v0.1.0.zip …View on GitHub ↗ -
v1.4.0 PhoneClaw v1.4.0 — MiniCPM-V 4.6 multimodal
Release notes excerpt
PhoneClaw v1.4.0 — MiniCPM-V 4.6 Multimodal Release date: 2026-05-12 (build 11 hotfix on 2026-05-12) 2026-05-12 Hotfix (build 11, same v1.4.0 tag) IPA re-uploaded with two follow-up fixes after initial v1.4.0 release: - MiniCPM-V markdown rendering — model output's literal \n escape sequences (2 chars) now decoded to real newlines, so ### headers, --- rules, and bullet lists render correctly in the chat view (previously they showed up as run-together inline text with visible \n). …View on GitHub ↗
FAQ
Does it require the internet or cloud inference?
Are there per-use fees or token limits for local operation?
Why did no permission dialog appear after installation?
Why can a model fail to load after switching?
allModels in LLM/Models/PredefinedModels.swift, that a shell-installed model finished downloading or a bundled model is in the app package, and that the device has sufficient memory.