Mobile App

The crystl mobile app is an iPhone companion to crystl for Mac. It pairs to a Mac you control and lets you watch your agents work, answer their questions, approve what they want to run, and keep a quest moving, all from your phone.

Available now. Download crystl on the App Store.

Everything happens between your two devices. Your code, terminal output, and conversations travel directly from your Mac to your phone: over your local network at home, or through an encrypted relay when you’re away. Nothing is stored on a server (see Privacy).

Pairing

The app has no account and no sign-in. You connect it to your Mac once:

1. On the Mac, open Window → pair device. crystl shows a QR code and, if you’re connecting from outside your local network, a remote-access toggle.
2. In the app, tap scan and point your phone at the QR code, or enter the host, port, and token by hand.

The pairing token is stored in your iPhone’s Keychain. Pairing and same-Wi-Fi use are free. To connect from outside your home network, enable remote access on the pair-device panel (Guild); traffic then routes through the encrypted relay to your Mac.

What you can do

Once paired, the app mirrors the parts of crystl you need when you’re away from the keyboard:

• See what needs you. The agents tab opens on an activity overview: every agent across your projects, with the ones waiting on you first (see the agents tab).
• Browse your work. See every open gem (project) and its shards (sessions), with each agent’s live status.
• Watch a session. Read the structured transcript of an agent’s turns, or switch to the live terminal screen.
• Answer questions. When your agent asks a multiple-choice question, it appears right in the conversation: tap to answer, no tab-switching.
• Approve tools. When your agent asks permission to run a tool, the request surfaces inline above the message box with allow, always, and deny, or review everything on the agents tab’s needs you list.
• Send and steer. Type a message to your agent, with a terminal key row (enter, esc, ctrl-c, arrows, tab) for driving full-screen terminal UIs.
• Dictate and attach. Use voice dictation to compose a message hands-free, or send a photo from your camera or library straight to your agent.
• Talk to your agent. Hold a whole spoken conversation without touching the phone (see talking to your agent).
• Open a project. Browse your Mac’s project folders and open a new gem from your phone.
• Pick your shortcuts. Choose which two or three sections sit in your tab bar, and in what order (see tab bar shortcuts).

On the same Wi-Fi, the app is free. When your phone and your Mac are on the same network, everything above works at no cost: watch your sessions and steer your agents (sending input, approving tools, merging a session). There’s nothing to buy inside the app.

Connecting from anywhere, reaching your Mac over the encrypted relay when you’re away from your home network, is part of Guild, the same membership that powers crystl’s Guild features on the desktop.

The agents tab

The agents tab is a cross-project view of every agent you’re running, opening on activity rather than a list of alerts.

At the top, needs you gathers the shards waiting on you, across every project, ordered by how urgent they are:

1. A shard waiting on a keypress: a question to answer or a tool to approve.
2. A shard that finished a turn and left something for you to read.
3. A shard that hit an error.
4. A shard waiting out a rate limit clock.

Tap a question or approval card to answer it right there. Tap any other row to open that agent’s conversation.

Below needs you, all agents lists every running agent, grouped by project, so you can check in on one even when it isn’t asking for anything.

Switch to notifications, the tab’s other view, for a running history: agent cards sent with crystl card, approvals and questions you’ve already acted on, and session finishes. Swipe a card to dismiss it, or clear the whole list. Tapping a card that came from a shard opens that shard.

Tab bar shortcuts

The tab bar holds two or three sections you choose, in the order you want them. Gems, agents, and schedules come first by default; quest starts in more.

To change them, go to Settings → tab bar shortcuts and pick a section for each slot. Leave the third slot on none to keep just two. Go back to apply your choices.

More always stays in the bar. It holds settings and whatever sections you didn’t pin, including quest by default, so nothing you add to the tab bar becomes unreachable.

Talking to your agent

Turn on read replies aloud and the phone speaks your agent’s replies. That switch is the feature’s on switch: turn it off and the speaker button goes away.

With it on, you can hold a whole conversation without touching the phone. The app listens, sends what you said, waits for the agent, reads the reply aloud, and opens the microphone again. Speak over a reply and it stops mid-sentence, which is how you interrupt.

It decides you have finished talking from your words rather than from a fixed pause, so a breath in the middle of a thought no longer cuts you off. A sentence that sounds finished sends quickly; one trailing off mid-thought, or ending on a comma, a conjunction, or half a number, waits longer.

Picking a voice. Replies are read in the best voice your phone has installed. These are Apple’s own voices, the ones VoiceOver uses, so a spoken reply sounds like a screen reader reading text aloud. The voice picker in settings speaks a sample when you tap one, so you can hear the difference before you choose. If only the flat built-in voices are on your phone, it says so and shows you how to download a better one.

Quests on your phone

If you’ve launched a quest, a party of agents working together, open it from more → quest, or pin it to your tab bar (see tab bar shortcuts):

• Follow the party chat. See the conversation between your heroes as it happens. Each hero speaks under its name and role, like Wizard (UI/UX).
• Chime in. Send a message to the whole party from your phone; it lands on the quest’s shared channel just like a message you’d type on the Mac.
• Hands off the heroes. Tapping an individual hero shows “this hero is in a quest” and routes you to the party chat, so a stray message can’t break the agents’ coordination by going to one agent instead of the group.

When no quest is running, the quest screen simply waits with an invitation to start one on your Mac.

Phone notifications

Turn on notifications and your phone alerts you the moment an agent needs you: a tool to approve, a question to answer, or a session that just finished. The alert carries only short labels (the project, session, and tool names) so you know what’s waiting; it never contains your messages, terminal output, or code. You can turn notifications off at any time in iOS Settings. Tapping an alert opens the agents tab, landing on needs you for a question or an approval, or on notifications for an agent card.

Requirements

• An iPhone running iOS 16.1 or later.
• A Mac running crystl, paired to the app.
• Both devices on the same network, or remote access enabled, to connect from anywhere through the relay.

Phone can’t reach your Mac?

If the macOS firewall is on, the first connection from your phone makes macOS ask whether crystl may accept incoming network connections. Click Allow and you’re done; macOS remembers the choice.

If that prompt was denied or dismissed, the phone can’t reach your Mac and nothing on screen says why. To fix it, open System Settings → Network → Firewall → Options, find crystl in the list, and set it to Allow incoming connections. Everything on the Mac itself (approvals, the CLI, panels) works either way; the firewall only affects connections from other devices, like your phone.

Privacy

The app collects no analytics and shows no ads. Your supervision data stays between your phone and your Mac; the only thing that leaves your devices is the push notification described above. Full details are in the privacy policy.