chums

Everyone is building a cute new assistant: another subscription, another app, another company holding your data. Chums is a team of agents on the AI you already pay for.

Each agent runs on Claude Code or Codex, picked per agent from the watch or the iPhone: docs/other-agents.md.

What you need: an Apple Watch on watchOS 26 and the iPhone it is paired with (iOS 26), a Mac with Apple silicon and Xcode 26, an Apple ID (a free one works), a free Tailscale account, and Claude Code or Codex. You build the apps from source and run the hub on your Mac. The first setup takes 20–30 minutes, plus up to half an hour of waiting for Xcode to prepare the watch and for a new Funnel address to reach public DNS. Requirements · Quickstart · Set it up with your agent

Set it up with your agent

Chums is source code, not an App Store download. Paste this into Claude Code or Codex on your Mac. It does the setup and stops when it needs your hands: signing in, plugging in your iPhone, turning on Developer Mode.

Set up Chums for me: clone https://github.com/lcoutodemos/chums and follow its AGENTS.md.

What you can do from the watch

• Talk to an agent. Hold the screen, say what you want, let go. The Mac transcribes it and sends it to the agent.
• See what it is doing. The character acts out the agent's state: listening, thinking, working, waiting for you, done, blocked. Each tool call appears on screen as it runs.
• Approve or deny actions. When the agent asks for permission, hold the card to allow it or tap × to deny it.
• Hear short replies. The agent answers in one short sentence, spoken on the watch in the character's own voice (with the voices installed), and kept in a conversation you can scroll.
• Get pictures. Ask for a screenshot of your screen, an app or a web page, or for something the agent made; it arrives as a picture you can zoom.
• Switch between agents. Each agent is its own session and character. Tap the faces at the top left to pick one; what you say goes to the one on screen. Another agent's news arrives as a haptic tap.
• Change who an agent is. Say what should be different about an agent (its name, what it looks after, how it talks) and save the change. What it runs on, its model, its permissions and its voice are a tap away.
• Carry it on your keys. Keyring mode keeps the app on screen with the watch off your wrist.

The iPhone app

The same agents and conversations, on a screen with room for them. Type or talk, send photos and files, approve, and change an agent: what it runs on, its model, its permissions, its voice and its soul.

What an agent shows you opens live. Ask for a chart and it makes an HTML page that runs on the iPhone: drag across it, switch what it shows. A web page loads, a PDF scrolls page by page, a table scrolls, a video plays, and Word, Excel, Keynote and other documents open in Quick Look (setup).

Widgets show the agents on the Home Screen and the Lock Screen and answer approvals; a control opens the app listening, from Control Center or the Action Button.

The characters

No big brand to obey, so each one tries a different way to build and animate a character: real-time 3D, Blender renders, vectors, one line, strokes on springs, plain eyes, pixels. Each is also its own agent, with its own conversation and voice. To make your own, start from Ray's Swift file: docs/characters.md.

The states come from what the agent reports: Claude Code through its hooks, Codex through its app-server.

The full map from hook events to states, including the ones the watch doesn't show yet, is in design/STATES.md.

How it works

flowchart LR
  W["Apple Watch<br/>Chums app"] -- "HTTPS + watch token" --> F["Tailscale Funnel"]
  F --> H["Hub on your Mac<br/>(Node.js)"]
  H <--> S["WhisperKit<br/>speech to text"]
  H <-- "localhost" --> C["Channel + hooks"]
  C <-- "MCP" --> A["Claude Code session"]
  H <-- "JSON-RPC" --> X["codex app-server"]

• The watch app (app/ChumsWatch, SwiftUI) draws the character, records your voice and polls the hub. The iPhone app (app/ChumsPhone) reaches the same hub with the same address and token.
• The hub (hub/hub.mjs) runs on your Mac. It tracks sessions, routes what you say, holds approvals, transcribes speech (WhisperKit) and voices the replies (Kokoro), all on the Mac.
• The channel and hooks (channel/) connect each Claude Code session to the hub. bin/chums-agents runs each Claude Code agent's session with both, in the background; bin/chums-claude starts one in a terminal.
• Codex agents are run by the hub itself through Codex's app-server protocol (hub/runtimes.mjs). bin/chums-codex opens a Codex terminal on the same conversation, so you can follow and type into it on the Mac.
• watchOS apps can't reliably reach an address on your home network, so the hub's watch API is published with Tailscale Funnel and protected by a token. See SECURITY.md for what that exposes.

Details: docs/architecture.md.

On your keys

Keyring mode keeps Chums on screen when nobody is wearing the watch, and your agents keep working on your Mac.