Yui | iOS app and Hermes plugin
Yui is a phone app for talking to your own AI agents. You chat like normal. When a button, a timer or a table would work better than text, the agent puts one on the screen, and your taps go straight back to it.
Yui brings no brain of its own. You bring the agent, and Yui gives it a face, a voice and a screen it can draw on. Hermes is the first agent it supports.
This repo holds the native SwiftUI app, the Swift Yui Lines parser, the Supabase backend and the Hermes plugin. The roadmap, the progress log and the Yui Lines spec live in the hub repo, postscarcityai/yuigui, and at yuigui.com. Every other platform has its own repo: see Every Yui.
What is in here
| Path | What it is |
|---|
Yui/ | The iOS app (SwiftUI, iOS 26, iPhone only) |
Packages/YuiLines/ | Swift parser for Yui Lines, no dependencies |
project.yml | XcodeGen project. The .xcodeproj is generated, not committed |
hermes-plugin/ | The yui Hermes platform plugin |
adapters/openclaw/ | Yui channel plugin for OpenClaw: an OpenClaw agent talks in Yui like a Hermes agent |
adapters/webhook/ | Webhook bridge, Python and Node: any agent that answers an HTTP POST |
adapters/n8n/ | n8n: the Yui node (ask on the phone, wait for the tap), MCP Client Tool and webhook workflows |
supabase/functions/yui-mcp/ | Yui MCP server: Claude Code, Cursor or any MCP client puts a screen on your phone and reads the taps back |
supabase/functions/yui-oauth/ | OAuth 2.1 for the MCP server: discovery, dynamic client registration, PKCE, approve in the app or with a pairing code, rotating refresh tokens |
supabase/ | Migrations, edge functions and live tests for accounts and agents |
scripts/ | TestFlight upload, test builds by link and App Store Connect helpers |
Run the app
You need a Mac with Xcode 26 and XcodeGen (brew install xcodegen).
export YUI_TEAM_ID=<your Apple team id> # or leave empty for the simulator
xcodegen generate
open Yui.xcodeproj
Pick an iPhone simulator and run. DEBUG builds take a few launch arguments for screenshots and offline work: -yuiDemoAccount (skip Sign in with Apple), -yuiSignedOut, -yuiAgents, -yuiNoAgents, -yuiAddAgent, -yuiAddAgentCode, -yuiSettingsLarge, -yuiConfirmDelete.
Parser tests:
cd Packages/YuiLines && swift test
The tests use Swift Testing, which needs full Xcode, not just the Command Line Tools. If swift test says no such module 'Testing', run sudo xcode-select -s /Applications/Xcode.app. One test checks that the bundled conformance vectors match the hub repo. When the hub adds a vector, run Packages/YuiLines/scripts/sync-vectors.sh with yuigui checked out next to this repo.
The app points at our Supabase project (Yui/Sources/Account/YuiBackend.swift). The key in that file is a public client key. It grants only the anon role, which cannot read any yui_ table. To run your own backend, create a Supabase project, apply supabase/migrations/ in order, deploy the functions in supabase/functions/, and change the URL and key in that file.
Connect Hermes
The yui plugin makes Yui a Hermes messaging platform, next to Telegram. Each Hermes profile you install it into gets its own thread in the app and keeps one memory across Yui and Telegram. It dials out to Supabase with a scoped connector token, so your machine opens no inbound ports.
-
In the app, go to Agents, tap Add agent, and note the six-digit code.
-
On the machine that runs Hermes:
hermes-plugin/install.sh <profile>
hermes -p <profile> yui pair <code>
hermes -p <profile> gateway restart
hermes -p <profile> yui status
-
The agent shows up in the app. Talk to it.
The plugin injects a short guide into each Yui turn so the agent knows it can put Yui Lines on screen (source: yuigui/spec/CHANNEL.md, synced by hermes-plugin/sync_channel.py). The connector credential lives at ~/.hermes/yui/connector.json, outside the repo.
Without Hermes loaded, python3 hermes-plugin/yui/connector.py pair <code> --profile <profile> does the same pairing. How messages, events and credentials flow: yuigui/spec/RELAY.md.
On OpenClaw? Install the channel plugin in adapters/openclaw/ (openclaw plugins install ./yui/adapters/openclaw), pair with openclaw yui pair <code>, restart the gateway. Your agent gets the channel guide every turn and answers with screens. Test: python3 adapters/openclaw/tests/openclaw_e2e.py.
Not on Hermes? Any agent that answers an HTTP POST can talk in Yui through the webhook bridge in adapters/webhook/ (Python stdlib or Node 20, no dependencies): pair it with the same code, point it at your agent's URL, and it delivers every message once, with the channel guide in each request. Ten-line example agents included. Test: python3 adapters/webhook/tests/webhook_e2e.py.
On Claude Code, Cursor or another MCP client? Add the Yui MCP server: pair with the app's code as kind mcp to get a token, then claude mcp add --transport http yui https://<ref>.supabase.co/functions/v1/yui-mcp --header "Authorization: Bearer yui_ct_...". Tools yui_show, yui_answers, yui_say, yui_threads; the channel guide is the yui_guide prompt. Steps and the contract: yuigui.com/developers/mcp. On an app that only does OAuth (the Claude and ChatGPT apps' custom connectors)? Paste the same URL with no header: it signs in through yui-oauth and you approve it in Yui. Tests: python3 supabase/tests/mcp_test.py (OAuth included), a real Claude Code against the simulator: supabase/tests/mcp_claude_e2e.py --sim <udid>, and the MCP SDK's own OAuth client against the simulator: supabase/tests/mcp_oauth_e2e.py --sim <udid>. The function parses what it is sent with a copy of the YL parser; python3 supabase/scripts/sync_yl.py refreshes it.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
