AiCLI

An iPhone command deck for AI providers running through your Mac.

Quickstart · How to Use · Install · Security

The iPhone app is the remote. The Mac Bridge runs on your Mac: it talks to CLI tools, local model apps, and provider endpoints, then streams results back to the phone.

iPhone App -> Mac Bridge -> Codex / Gemini / Ollama / oMLX / Local Providers

The iPhone app alone is not enough. The Mac Bridge must be installed and running on your Mac.

What This Is

I wanted a real iPhone app for the AI tools already running on my Mac. Not a web wrapper, not a hosted service, and not another place to copy/paste between apps.

AiCLI is that: a small native iPhone app that talks to a local Bridge on your Mac. The Bridge handles the provider work. The phone stays focused on picking a provider, sending prompts, organizing threads, and reading results.

It is a working MVP. It is also still early. Expect some rough edges around setup, physical-device QA, and provider quirks.

Screenshots

  

What It Can Do Today

• Chat from an iPhone with AI providers configured on your Mac.
• Use local providers such as Ollama and oMLX.
• Use CLI providers such as Codex and Gemini.
• Organize work into projects and threads.
• Rename threads and add per-thread instructions.
• Copy messages or full threads.
• Switch themes, fonts, and text size.
• Keep unavailable or setup-only providers out of the chat picker.

Status

AiCLI is real and usable, but still early.

Working now:

• Native SwiftUI iPhone app.
• Mac Bridge with token auth on all non-health routes.
• WebSocket run streams with auth.
• Projects, threads, rename, and per-thread system prompts.
• Provider visibility: enabled, disabled, hidden, setup-only.
• Project Memory: visible project-scoped notes, stored on the Mac Bridge, off by default until enabled per project.
• Project Memory has been verified on a physical iPhone: add/edit/delete/enable/disable works, Manual mode injects enabled notes, and Off mode does not inject memory.
• Conservative permission enforcement on the Bridge.
• Fake, Gemini, explicit Codex codex:gpt-5.4, oMLX, and Ollama qwen2.5:0.5b.
• Bridge-owned provider credential storage for oMLX API key setup from the iPhone.
• Bridge-owned Project Memory store and authenticated memory endpoints.
• Hermes setup/status scaffolding, with Hermes runtime intentionally disabled.
• Lightweight activity display instead of raw provider protocol logs.
• Repo-based Mac Bridge menu helper for Start, Stop, Restart, Status, Logs, and Config.
• Bridge helper scripts wait for /health before claiming the Bridge is ready and report unhealthy starts more clearly.
• Physical iPhone builds for bundle ID com.aicli.app.
• Tailscale Serve HTTPS works with a MagicDNS phone URL.

Still needs more hands-on checking:

• oMLX phone UI smoke after saving/restoring the API key from Provider Settings.
• Long oMLX background/lock/reopen behavior.
• Copy/paste, Provider Settings taps, Data Management, thread deletion gestures, and theme/text-size checks.

Quickstart

Most people should use the Mac Bridge DMG from GitHub Releases. Developers who want to run from source can clone the repo instead.

Either way, the iPhone app still needs the Mac Bridge. The phone is the control surface; the Mac Bridge is what talks to providers on your Mac.

Path 1: Easy DMG Setup

This is the normal path once release builds are available.

1. Download the AiCLI Mac Bridge DMG from GitHub Releases.
2. Open the DMG.
3. Double-click AiCLI Bridge.app.
4. Wait for the Bridge status to say it is ready.
5. Copy the Bridge URL and Bridge token from the menu bar helper.
6. Open AiCLI on your iPhone.
7. Paste the URL and token into Bridge settings.
8. Pick a ready provider.
9. Send a quick test prompt.

For a physical iPhone, use the HTTPS phone URL shown by the Bridge helper. With Tailscale Serve this is usually the MagicDNS root URL without :43721.

Path 2: Developer / Clone Setup

Use this if you want to run AiCLI from source.

Clone the repo:

git clone https://github.com/stamsam/AiCLI.git
cd AiCLI

Install dependencies:

npm install

Start the Bridge:

./scripts/start-bridge.sh

Or launch the early menu bar helper:

./scripts/run-bridge-menu.sh

The menu bar helper launches in the background and shows an icon-only AiCLI prompt mark in the macOS menu bar. It gives you Start, Stop, Restart, Status, Logs, Config, and copy actions without keeping a Terminal window open.

Check status:

./scripts/status-bridge.sh

Status shows the local Simulator URL, the detected HTTPS phone URL when Tailscale is available, whether the Bridge is ready, log path, provider count, and the token file path. It does not print the token.

Copy the Bridge token without printing it:

cat "$HOME/Library/Application Support/AiCLI/bridge-token" | pbcopy

In the iPhone app, open Bridge settings and enter the Bridge URL and token:

Bridge URL: http://127.0.0.1:43721       # Simulator only
Bridge URL: https://your-mac.tailnet-name.ts.net        # physical iPhone with Tailscale Serve
Bridge Token: paste the token

Then pick a provider and send a test prompt.

If you want the install script to create local folders and Desktop helpers, run:

./scripts/install-bridge.sh

For a real iPhone, use the HTTPS phone URL shown by the status helper or menu bar helper. If you want to pin it explicitly, set AICLI_PHONE_URL=https://your-mac.your-tailnet.ts.net. Do not use 127.0.0.1 on the phone; that points to the phone itself.

Keep Private Data Out Of Git

Do not commit secrets, Bridge tokens, provider API keys, Project Memory files, provider secret stores, sessions, projects, run logs, local provider configs, screenshots with private data, or anything from your local runtime folders.

Security, Briefly

The Bridge can run provider CLIs and talk to local model servers on your Mac. Treat it like a private developer tool.

• The Bridge defaults to 127.0.0.1.
• Network or Tailscale access requires a Bridge token.
• For physical iPhone use, prefer HTTPS over Tailscale/MagicDNS.
• Do not expose the Bridge directly to the public internet.
• Use Tailscale or a trusted private LAN for physical iPhone testing.
• Keep provider API keys in local environment/config files only.
• Do not commit sessions, logs, provider preferences, tokens, or screenshots with private data.

See docs/SECURITY.md.

Providers

Ready or commonly used:

• Fake: local test provider.
• Codex CLI: explicit codex:gpt-5.4 is the tested path.
• Gemini CLI: works when installed and authenticated locally.
• oMLX: OpenAI-compatible local endpoint.
• Ollama: tested with qwen2.5:0.5b.
• LM Studio: works when the LM Studio server is already running.

Setup-only or adapter-pending:

• Hermes Agent: setup/status only; runtime, gateway, tools, cron, memory sync, and subagents are disabled.
• Claude/Mistral/OpenCode/Qwen: visible as setup/missing/adapter-pending states until runtime support is explicitly implemented.

See docs/PROVIDERS.md.

How To Use It

Start with docs/USAGE.md. It covers:

• starting the Bridge
• connecting the iPhone app
• choosing a provider
• creating chats and projects
• adding visible project memory notes
• using thread instructions
• copy/paste
• themes and text size
• troubleshooting common connection/provider problems

Installation

See docs/INSTALL.md for a fuller install guide, including requirements, iPhone setup, provider setup, and troubleshooting.

Build The iPhone App

Open apps/iphone/AiCLI.xcodeproj in Xcode, select the AiCLI scheme, choose your Apple Developer Team, then build and run on a connected iPhone.

You can also build from Terminal:

xcodebuild -project apps/iphone/AiCLI.xcodeproj -scheme AiCLI -destination 'generic/platform=iOS Simulator' build
xcodebuild -project apps/iphone/AiCLI.xcodeproj -scheme AiCLI -destination 'generic/platform=iOS' build

The iPhone app still needs the Mac Bridge running separately. For physical iPhone testing, use the HTTPS Tailscale URL shown by the Bridge status helper and paste the Bridge token into the app.

Development

For local Bridge development:

npm install
npm run dev:bridge

Validation:

npm run typecheck
npm run test:security
xcodebuild -project apps/iphone/AiCLI.xcodeproj -scheme AiCLI -destination 'generic/platform=iOS Simulator' build

Repository layout:

• apps/iphone - native SwiftUI app.
• apps/bridge - TypeScript Mac Bridge.
• apps/mac-bridge - early macOS menu bar Bridge helper.
• packages/protocol - shared protocol types.
• packages/core - shared helpers.
• scripts - Bridge install/start/stop/status/menu scripts.
• docs - install, usage, security, provider, deployment, and release notes.
• docs/MEMORY.md - Project Memory behavior and privacy notes.

What I’m Working On Next

• Better physical-device QA coverage.
• Friendlier Provider Setup flows.
• Package the Mac Bridge menu helper as a signed app.
• Signed and notarized DMG for the Bridge.
• TestFlight distribution for the iPhone app.
• Hermes runtime only after a dedicated security/permissions pass.
• Broader LM Studio and custom local endpoint validation.

License

AiCLI is licensed under the MIT License. See LICENSE.

Third-party dependencies and bundled assets remain under their respective licenses. The bundled JetBrains Mono fonts remain under the SIL Open Font License included at apps/iphone/Resources/Fonts/JetBrainsMono/OFL.txt.

Questions

Questions or feedback? Find me on X: @Stamatiou

Development Notes

The dated implementation history lives in docs/DEVLOG.md.