Talk to Claude Code and Codex agents from an Apple Watch and an iPhone. Each agent is a character on the watch.
#!/usr/bin/env node
// Chums channel: a Claude Code channel (MCP server) that connects one session to the Chums hub.
// in: orders spoken on the watch -> notifications/claude/channel
// out: chums_reply tool -> one spoken line on the watch
// both ways: permission prompts -> approval card on the watch -> allow/deny verdict
// Launched by Claude Code (see bin/chums-claude). Talks to the hub over localhost HTTP.
//
// Tools only (CHUMS_SESSION set): for agents the hub itself drives (Codex, Copilot and other Agent Client Protocol
// agents, hub/runtimes.mjs), which give it to their agent as an ordinary MCP server. The hub already knows the session
// and brings it orders and verdicts, so this only offers chums_reply and chums_show for that session: no channel, no
// registering, no polling.
import os from 'node:os'
import fs from 'node:fs'
import path from 'node:path'
import crypto from 'node:crypto'
import { execFile } from 'node:child_process'
import { Server } from '@modelcontextprotocol/sdk/server/index.js'
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js'
import { z } from 'zod'
import { MAX_WORDS, PHONE_WORDS, WATCH_GUIDE, PAGE_GUIDE, OWNER, Owner, wordsFor } from '../hub/standing.mjs'
const toolsOnly = !!process.env.CHUMS_SESSION
// a hub-driven agent's MCP server gets the hub's address from the hub, and its token or the file that has it (its HOME
// may be another)
const CONFIG = process.env.CHUMS_CONFIG || path.join(os.homedir(), '.chums', 'config.json')
let cfg
try { cfg = process.env.CHUMS_HUB && process.env.CHUMS_TOKEN ? { token: process.env.CHUMS_TOKEN } : JSON.parse(fs.readFileSync(CONFIG, 'utf8')) }
catch (e) {
// (not e.message: a JSON error quotes the file, and the file holds the token)
process.stderr.write(`[chums] can't read ${CONFIG} (${e.code ?? 'not valid JSON'}). Start the hub once (bin/chums-hub): it writes it.\n`)
process.exit(1)
}
const HUB = process.env.CHUMS_HUB || `http://127.0.0.1:${cfg.port}`
const sessionId = process.env.CHUMS_SESSION || crypto.randomUUID()
const name = process.env.CHUMS_NAME || path.basename(process.cwd())
const err = (...a) => process.stderr.write(`[chums] ${a.join(' ')}\n`)
async function hub(pathname, body, method = body ? 'POST' : 'GET') {
const res = await fetch(HUB + pathname, {
method,
headers: { authorization: `Bearer ${cfg.token}`, 'content-type': 'application/json' },
body: body ? JSON.stringify(body) : undefined,
})
if (!res.ok) {
const why = await res.json().then(b => b.error).catch(() => null)
throw Object.assign(new Error(why ?? `hub ${res.status} ${pathname}`), { status: res.status })
}
return res.json()
}
const mcp = new Server(
{ name: 'chums', version: '0.1.0' },
{
capabilities: toolsOnly ? { tools: {} } : {
experimental: { 'claude/channel': {}, 'claude/channel/permission': {} },
tools: {},
},
instructions: toolsOnly ? WATCH_GUIDE : [
`${Owner} talks to this session (named "${name}") from an Apple Watch, often away from the desk.`,
`${Owner}'s messages arrive as <channel source="chums" utterance_id="..." via="watch"> or via="phone"; from the watch they are voice transcripts, so expect recognition errors and read for intent.`,
'Do the work exactly as if it had been typed here.',
`Whenever you finish work ${OWNER} asked for from the watch, or you need ${OWNER}, call the chums_reply tool.`,
'The watch is a small conversational companion, not a reading surface: reply like a quick text message, about 8 words,',
`${MAX_WORDS} at most (the tool refuses longer). Result first, plain words, no preamble, no restating what was said,`,
'no explanations. If there is more to say, it stays on the Mac: say "Details on your Mac."',
`From the iPhone (via="phone") the reply is shown as text: give the answer itself in plain sentences, ${PHONE_WORDS} words at most, still no code, paths, URLs, markdown or lists.`,
'Never include code, file paths, URLs, markdown or lists; they are read aloud.',
"Set status: 'done' when finished, 'question' when you need an answer, 'blocked' when you cannot continue, 'working' only for a rare progress note on long tasks.",
`To ask ${OWNER} something (a choice, a go-ahead), call chums_reply with status 'question' and wait: the answer comes as the next message. Don't use AskUserQuestion: its dialog shows only in this terminal, where nobody is.`,
'Only use chums_reply for messages that came from the watch, not for messages typed in the terminal.',
'The watch shows and speaks every chums_reply; you cannot see or hear it, and that is expected.',
`If ${OWNER} asks whether you can hear, just answer. Never investigate the watch app or the hub unless asked to.`,
`Never start replies with a name or give yourself one: on the watch you appear as the character ${OWNER} picked.`,
`When ${OWNER} asks to see something (the screen, an app or browser tab, a web page, a file, an image, a chart), or you made something visual that was asked for, call chums_show instead of chums_reply: it puts a picture in the watch chat that can be opened and zoomed, and says its text; the iPhone opens the file itself.`,
"For the whole screen use screenshot: 'screen'; for an app use its name, e.g. screenshot: 'Safari'. chums_show finds the app's window itself and is quick: call it first, without looking for apps, windows or browser extensions some other way. If what's wanted isn't on screen in that app (a Stripe dashboard, say), also pass open: its URL, and it opens there before the screenshot. Pages that need a login (dashboards, mail) are screenshots of the browser; a public page is url; a file is file (a page, a document, a PDF, text or code, a table, an image or a video). If it fails, the error says why and which apps have windows open.", PAGE_GUIDE,
].join(' '),
},
)
// For hub-driven agents: neither tool changes anything on the Mac (one speaks on the watch, the other shows a picture
// there), so agents that ask before MCP tool calls that might can run them without asking.
const QUIET = { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: false }
mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
tools: [{
name: 'chums_reply',
description: `Speak one short sentence to ${OWNER} on the Apple Watch. Use after finishing or when you need ${OWNER}.`,
inputSchema: {
type: 'object',
properties: {
text: { type: 'string', description: `One short spoken sentence, like a text message: about 8 words, ${MAX_WORDS} at most (to the iPhone: plain sentences, ${PHONE_WORDS} words at most). No code, paths or URLs.` },
status: { type: 'string', enum: ['done', 'question', 'blocked', 'working'] },
},
required: ['text'],
},
...(toolsOnly ? { annotations: QUIET } : {}),
}, {
name: 'chums_show',
description: `Show ${OWNER} something on the Apple Watch and the iPhone: a screenshot of the screen or an app window, a web page, or a file: a page, a document, a PDF, text or code, a table, an image or a video. The watch shows it as a picture that can be opened and zoomed (a video as a still), with a short spoken line; the iPhone opens the file itself. ${PAGE_GUIDE}`,
inputSchema: {
type: 'object',
properties: {
screenshot: { type: 'string', description: "'screen' for the whole display, or an app's name (e.g. 'Safari') for its front window." },
open: { type: 'string', description: "With screenshot of an app: a URL to open in that app first (e.g. 'https://dashboard.stripe.com'), for when what's wanted isn't already on screen there." },
url: { type: 'string', description: 'A public web page to render at phone width (not one behind a login: screenshot the browser instead).' },
file: { type: 'string', description: 'Absolute path of the file: HTML or SVG, PDF, Markdown, text or code, CSV or TSV, an image, a video (.mov, .mp4, .m4v), or a document macOS previews (Word, Excel, PowerPoint, Pages, Keynote, Numbers, RTF, EPUB, USDZ).' },
title: { type: 'string', description: 'Two to four words, shown on the watch, e.g. "Stripe dashboard".' },
text: { type: 'string', description: `One short spoken line, like a reply: ${MAX_WORDS} words at most.` },
},
},
...(toolsOnly ? { annotations: QUIET } : {}),
}],
}))
// a screenshot of the whole screen, or of an app's front window, as a PNG. It needs the Screen Recording permission of
// the app this session runs in (macOS asks for it, or it's in System Settings › Privacy & Security).
const sh = (cmd, args) => new Promise((resolve, reject) => execFile(cmd, args, { timeout: 15_000 }, (e, out, errOut) => e ? reject(new Error(String(errOut || e.message).trim())) : resolve(String(out).trim())))
async function screenshot(target) {
const out = path.join(os.tmpdir(), `chums-shot-${Date.now()}.png`)
if (/^(screen|desktop|display|everything)$/i.test(target)) { await sh('/usr/sbin/screencapture', ['-x', out]); return { file: out, from: 'screen' } }
const js = `ObjC.import("CoreGraphics");
const all = ObjC.deepUnwrap(ObjC.castRefToObject($.CGWindowListCopyWindowInfo($.kCGWindowListOptionAll | $.kCGWindowListExcludeDesktopElements, $.kCGNullWindowID)));
const want = ${JSON.stringify(target.toLowerCase())};
const w = all.filter(w => w.kCGWindowLayer === 0 && (w.kCGWindowOwnerName || "").toLowerCase().includes(want) && w.kCGWindowBounds.Height > 150 && w.kCGWindowBounds.Width > 150)
.sort((a, b) => (b.kCGWindowIsOnscreen ? 1 : 0) - (a.kCGWindowIsOnscreen ? 1 : 0));
w.length ? w[0].kCGWindowNumber + " " + w[0].kCGWindowOwnerName : ""`
const found = await sh('/usr/bin/osascript', ['-l', 'JavaScript', '-e', js])
if (!found) {
// say which apps do have windows, so the session can pick the right one
const open = await sh('/usr/bin/osascript', ['-l', 'JavaScript', '-e', `ObjC.import("CoreGraphics");
const all = ObjC.deepUnwrap(ObjC.castRefToObject($.CGWindowListCopyWindowInfo($.kCGWindowListOptionAll | $.kCGWindowListExcludeDesktopElements, $.kCGNullWindowID)));
[...new Set(all.filter(w => w.kCGWindowLayer === 0 && w.kCGWindowBounds.Height > 150).map(w => w.kCGWindowOwnerName))].join(", ")`]).catch(() => '')
throw new Error(`No open window of ${target}.${open ? ` Apps with windows open: ${open}.` : ''}`)
}
const [wid, ...owner] = found.split(' ')
await sh('/usr/sbin/screencapture', ['-x', '-o', '-l', wid, out])
return { file: out, from: owner.join(' ') }
}
const PERMISSION = `macOS refused the screenshot: the app this session runs in needs Screen Recording (System Settings › Privacy & Security › Screen & System Audio Recording). Tell ${OWNER}, in a few words.`
mcp.setRequestHandler(CallToolRequestSchema, async req => {
if (req.params.name === 'chums_show') return show(req.params.arguments ?? {})
if (req.params.name !== 'chums_reply') throw new Error(`unknown tool: ${req.params.name}`)
const { text, status = 'done' } = req.params.arguments ?? {}
// the watch shows a line or two and reads it aloud: refuse anything longer, so the session says it again, shorter
// (the iPhone shows the text: a few sentences)
const words = String(text ?? '').trim().split(/\s+/).filter(Boolean).length, limit = wordsFor(lastVia)
if (words > limit) {
const where = lastVia === 'phone' ? 'the iPhone' : 'the watch'
return { content: [{ type: 'text', text: `Too long for ${where} (${words} words). Say it again in ${limit} words or fewer; details stay on the Mac.` }], isError: true }
}
try {
await hub('/channel/reply', { sessionId, text: String(text), status })
return { content: [{ type: 'text', text: 'Spoken on the watch.' }] }
} catch (e) {
return { content: [{ type: 'text', text: `The watch hub is unreachable (${e.message}); ${OWNER} did not hear this.` }], isError: true }
}
})
async function show({ screenshot: target, open: openURL, url, file, title, text }) {
const fail = t => ({ content: [{ type: 'text', text: t }], isError: true })
const words = String(text ?? '').trim().split(/\s+/).filter(Boolean).length
if (words > wordsFor(lastVia)) return fail(`Too long (${words} words). Say it in ${wordsFor(lastVia)} words or fewer.`)
if (!target && !url && !file) return fail('Give screenshot, url or file.')
let shot
if (target) {
// what's wanted isn't on screen yet: open it in that app, and give the page a moment to load
if (openURL && !/^(screen|desktop|display|everything)$/i.test(target)) {
try { await sh('/usr/bin/open', ['-a', String(target), String(openURL)]); await new Promise(r => setTimeout(r, 3500)) }
catch (e) { return fail(`Couldn't open ${openURL} in ${target}: ${e.message}`) }
}
try { shot = await screenshot(String(target)) }
catch (e) { return fail(/could not create image|not permitted|denied/i.test(e.message) ? PERMISSION : `Screenshot failed: ${e.message}`) }
}
try {
const a = await hub('/channel/artifact', {
sessionId, file: shot?.file ?? file, url, title: title ?? (shot ? shot.from : undefined), text,
kind: shot ? 'screenshot' : undefined, from: shot?.from,
})
return { content: [{ type: 'text', text: `Shown on the watch: ${a.title} (${a.w}×${a.h}).` }] }
} catch (e) {
return fail(e.status === 422 ? `The watch couldn't show it: ${e.message}` : `The watch hub is unreachable (${e.message}); ${OWNER} did not see this.`)
} finally { if (shot) fs.rm(shot.file, () => {}) }
}
const PermissionRequest = z.object({
method: z.literal('notifications/claude/channel/permission_request'),
params: z.object({
request_id: z.string(),
tool_name: z.string(),
description: z.string(),
input_preview: z.string(),
}),
})
mcp.setNotificationHandler(PermissionRequest, async ({ params }) => {
try { await hub('/channel/permission', { sessionId, ...params }) }
catch (e) { err('could not relay permission request:', e.message) }
})
await mcp.connect(new StdioServerTransport())
// ---- hub loop: register, then long-poll for orders and verdicts ----
// Each item is acknowledged on the next poll; the hub sends it again until then, so ids already handled are skipped.
let registered = false
let lastVia = 'watch' // where the latest order was said: its reply's length follows
const handled = new Set(), handledOrder = []
async function loop() {
let ack = []
for (;;) {
try {
if (!registered) {
await hub('/channel/register', { sessionId, name, cwd: process.cwd() })
registered = true
err('connected to hub as', name)
}
const { items } = await hub(`/channel/next?sessionId=${sessionId}${ack.length ? `&ack=${ack.join(',')}` : ''}`)
ack = items.map(it => it.id).filter(Boolean)
for (const it of items) {
if (it.id && handled.has(it.id)) continue
if (it.id) { handled.add(it.id); handledOrder.push(it.id); if (handledOrder.length > 500) handled.delete(handledOrder.shift()) }
if (it.type === 'order') {
lastVia = it.device === 'phone' ? 'phone' : 'watch'
await mcp.notification({
method: 'notifications/claude/channel',
params: { content: it.text, meta: { utterance_id: it.utteranceId, via: lastVia } },
})
} else if (it.type === 'verdict') {
await mcp.notification({
method: 'notifications/claude/channel/permission',
params: { request_id: it.requestId, behavior: it.behavior },
})
}
}
} catch (e) {
// 404: the hub restarted and forgot us, re-register now. Anything else: hub down, retry in 5 s.
registered = false
if (e.status !== 404) await new Promise(r => setTimeout(r, 5000))
}
}
}
const bye = () => { hub('/channel/bye', { sessionId }).catch(() => {}).finally(() => process.exit(0)) }
if (toolsOnly) process.stdin.on('end', () => process.exit(0)) // the hub owns this session: no register, poll or bye
else {
loop()
process.stdin.on('end', bye)
process.on('SIGTERM', bye)
}