AgentBase

Talk to your whole Claude Code fleet — from your iPhone.

Hold a button, speak, and steer a whole fleet of Claude Code agents running on your machine. It answers back, out loud. No API key, no ports to expose — the app connects to your box over SSH, the same way you already do.

---

What it is

Your agents live in tmux on a machine that already has your Claude Code logged in (your Mac, or a VPS). AgentBase is the phone in your pocket for that box:

• A live feed of agents. Each running Claude session is a row — like a Voice Memos list. Tap one to read it.
• Push-to-talk manager. Hold the red button and say what you want ("spin up a session to set up CI", "tell the auth agent to add tests"). Your words are transcribed on-device, sent to a manager that figures out whether to spawn a new agent, message an existing one, or answer you — and it can do several at once.
• A conversation, not a terminal. An agent's updates come in as chat messages; when one stops for a decision, its menu becomes tappable buttons. Answers can be read aloud.
• It reconnects when you come back to it, and picks up exactly where it left off — the same agents are still there when you SSH into the box from your laptop.

The idea came from Body of Lies: running a live operation from your phone while the rest of your day goes on. See the build story in docs/article.md.

What you'll need

To run the app	You need
A Mac	macOS with Xcode 26 — to build the app onto your phone (one-time)
An iPhone	iOS 17+, and a cable to install the first build
A "box"	any machine you can SSH into that has your fleet's tools installed

Your box is where the agents actually run. It can be your own Mac, or a remote Linux VPS. It needs these on PATH:

• claude — Claude Code, already logged in (this is the whole point: the app borrows the session you already have; there's no API key to wire up)
• tmux, node, and jq
• SSH access with the username, host/IP, and a project folder — exactly what you'd type into a terminal.

You don't install anything else on the box by hand. The first time you connect, the app uploads its scripts and starts the backend for you.

Run it on your iPhone

1 · Build and install the app (one-time, ~10 min)

brew install xcodegen            # once
cd ios && xcodegen generate      # creates AgentBase.xcodeproj
open AgentBase.xcodeproj

In Xcode:

1. Select the AgentBase target → Signing & Capabilities → tick Automatically manage signing, pick your Team, and set a unique Bundle Identifier (e.g. com.yourname.agentbase).
2. Plug in your iPhone and choose it in the run-destination dropdown.
3. Press Run (⌘R).

First run on a device:

• iPhone → Settings → Privacy & Security → Developer Mode → on → reboot.
• After the app installs: Settings → General → VPN & Device Management → trust your developer certificate.
• Launch it and allow the Microphone and Speech Recognition prompts.

Just want to see it first? In Xcode pick any iPhone Simulator instead of a device and press ⌘R — no signing or Developer Mode needed.

2 · Connect to your box

Open the app → the gear (Settings) → the remote (ssh) section, and enter:

Field	Example
Host / IP	your-box.example.com (or your-mac.local on the same Wi-Fi)
Port	22
Username	you
Project folder	/home/you/projects/myapp — where agents spawn

Tap Connect. On the first connection the app SSHes in, installs the fleet scripts if they aren't there, starts the server on the box, and tunnels it back to your phone over the SSH connection. When the status reads Connected, you're live. (Nothing is exposed to the public internet — the server only ever listens on the box's localhost.)

Connecting to your own Mac? Enable System Settings → General → Sharing → Remote Login, then use your Mac's username and your-mac.local as the host.

3 · Use it

• Hold the red button, speak your request, release. The manager acts on it and the feed updates.
• Tap an agent to open it as a chat thread — read its latest update, or type a follow-up.
• When an agent needs a decision, tap one of the buttons it shows; the raw terminal is one tap away for anything it can't parse.
• In Settings, toggle Read summaries aloud and pick a voice for the spoken read-back.

Troubleshooting

• "Not connected" after switching apps. iOS suspends the SSH link in the background; reopen the app and it reconnects automatically.
• Connect fails. From a terminal, confirm ssh <user>@<host> works and that claude, tmux, node, and jq are on the box's PATH. Make sure claude is logged in there (claude should start without asking you to sign in).
• Out and about. For a box at home/office, put both the phone and the box on Tailscale and use the box's tailnet IP as the host — a plain home IP won't be reachable from cellular.
• No voices / robotic read-back. iPhone → Settings → Accessibility → Spoken Content → Voices to download a Premium/Enhanced voice, then pick it in the app's Settings.

---

Under the hood (for the curious / developers)

Everything the app does is also a plain command on the box — no database, no cloud. State is just JSON in ~/.agentbase/.

bin/agentbase spawn --model haiku auth "refactor the auth module"   # start an agent
bin/agentbase manager "tell the auth agent to add tests"            # natural-language routing
bin/agentbase-watch status                                          # what every agent is doing

The app talks to bin/agentbase-server.js (Node stdlib, HTTP/JSON + SSE) running on the box; you can hit the same endpoints with curl, or open its built-in web client at http://127.0.0.1:8787/. Workers boot with lifecycle hooks auto-installed, so their state and summaries update on their own.

• bin/ — the runtime: agentbase, agentbase-watch, agentbase-server.js, and agentbase-connect (deploy to a remote box from the CLI).
• ios/ — the SwiftUI app (see ios/README.md for the file-by-file tour and manual Xcode setup).
• docs/DESIGN.md — architecture, the hook→state model, security, and the SSH bridge in detail.

Status: the fleet backend (spawn / route / read / hook-driven state) and the Node server are implemented and verified end-to-end; the SwiftUI app is the native client that drives them. prototypes/watch-pane.sh is the original tmux-pane summariser the whole thing grew out of.