Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

feat(agents): per-terminal Claude Remote Control toggle; drop the toolbar one

review84abc436d58e
diff --git a/CLAUDE.md b/CLAUDE.md
index 46754c64f..c4807224f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -5016,6 +5016,29 @@ command-bearing opens; this does not add a human-confirm dialog or change mobile
cleared by a `CronDelete` `recurring`-end event or the card's own × (dismisses the card only).
`clearForParent` (new turn) leaves the loop card's dragged position alone. Renders an ephemeral
**LoopNode** labelled by kind, connected by an edge to the parent, plus a small header badge.
+- **Claude Remote Control toggle** (agents in `REMOTE_CONTROL_CAPABLE` — claude only) — an antenna
+ button in the terminal header, right of the context meter, and in the kanban card modal (ONE
+ component, `components/RemoteControlButton.tsx`). Green = this session is reachable from
+ claude.ai / the Claude app; a click types Claude's own `/remote-control` into the session. It
+ replaced a short-lived app-wide toolbar toggle for the PHONE RELAY, which read as unrelated to
+ any terminal. Rules a refactor must keep:
+ - **State is read from the transcript, because no hook exists** (`core/remote-control-scan.ts`,
+ fed by both context tails → `agent:remote-control` → `state/remoteControl.ts`). ON is a
+ `system`/`bridge_status` record, OFF a `local_command` record whose stdout says "Remote Control
+ disconnected"; the latest wins. **Only the `local_command` shape is measured** (2.1.325); the
+ other two strings come from the CLI's source and no live connect has been run against the
+ parser. It therefore matches exactly and degrades to OFF — it can under-report, never invent ON.
+ - **The command is one toggle with two different dialogs.** OFF→ON may show a one-time "Enable
+ Remote Control?" consent (measured) — never answered by us. ON→OFF opens a dialog whose first
+ row is "Disconnect this session"; we press Enter **only after reading the pane and finding the
+ cursor on that exact row** (`disconnectRowSelected`). A timer-based Enter would accept the
+ consent dialog whenever our state was stale. The card modal has no live write, so there the
+ dialog is left for the user.
+ - Refused while `blocked`/`waiting` (typed text ANSWERS a prompt); allowed while `working` (the
+ command is `immediate`). Hidden on relay tabs (no local tail). Server Edition: works (same core
+ helper, real bridge subscription). Mobile: N/A.
+ - Owed device checks: a real connect turns it green; a real disconnect turns it off and the
+ gated Enter fires; state after an app restart and after `--resume`.
- **Branch conversation** — node action (`IconBranch`, Claude-only via `BRANCH_CAPABLE`): sends `/branch` into the
existing terminal via `pty.sendText` (tmux `send-keys`) and opens a new Claude node that
resumes the parked original with `claude --settings … -r <ORIGINAL_ID>`. The original id is
diff --git a/src/core/context-tail.test.ts b/src/core/context-tail.test.ts
index 8afb47a66..263c4d658 100644
--- a/src/core/context-tail.test.ts
+++ b/src/core/context-tail.test.ts
@@ -102,6 +102,30 @@ describe('createContextTail — task notifications', () => {
})
+describe('createContextTail — Remote Control', () => {
+ it('reports the state already in the transcript, then each change', async () => {
+ const dir = testTmpDir('ctxtail-rc-')
+ const file = path.join(dir, 'sess.jsonl')
+ const on = JSON.stringify({ type: 'system', subtype: 'bridge_status', url: 'https://claude.ai/code/x' })
+ const off = JSON.stringify({
+ type: 'system',
+ subtype: 'local_command',
+ content: '<local-command-stdout>Remote Control disconnected.</local-command-stdout>'
+ })
+ fs.writeFileSync(file, on + '\n')
+ const onRemoteControl = vi.fn()
+ const tail = createContextTail(vi.fn(), { onRemoteControl })
+ tail.track('s1', file)
+ await new Promise((r) => setTimeout(r, 1300))
+ expect(onRemoteControl.mock.calls).toEqual([['s1', true]])
+ fs.appendFileSync(file, off + '\n')
+ await new Promise((r) => setTimeout(r, 1300))
+ expect(onRemoteControl.mock.calls).toEqual([['s1', true], ['s1', false]])
+ tail.untrack('s1')
+ }, 8000)
+})
+
+
describe('createContextTail — the `parse` dep (gemini/codex)', () => {
/** Write a transcript, tail it with `parse`, and return whatever it pushed. */
async function pushesFor(
diff --git a/src/core/context-tail.ts b/src/core/context-tail.ts
index 925f75857..bce462639 100644
--- a/src/core/context-tail.ts
+++ b/src/core/context-tail.ts
@@ -6,6 +6,7 @@ import fs from 'fs'
import type { ContextWindowUsage } from '../shared/types'
import { cachedWindowFor } from './model-window'
import { splitCompleteLines } from './subagent-tail'
+import { parseRemoteControl } from './remote-control-scan'
import { claudeInterruptMarkerOf } from '../shared/agents/claude-interrupt'
const POLL_MS = 1000
@@ -261,6 +262,10 @@ export interface ContextTailOptions {
/** Fired when a tracked session's transcript records a turn INTERRUPT marker, with that turn's id
* — see `parseTurnInterrupts`. Claude only; the consumer decides whether it is the live turn. */
onTurnInterrupted?: (sessionId: string, turnId: string) => void
+ /** Fired when a tracked session's transcript records Claude Remote Control connecting (`true`)
+ * or disconnecting (`false`) — see `parseRemoteControl`. Claude only. A STATE, not an event:
+ * the latest record in a read wins, and a read of old history may report it too. */
+ onRemoteControl?: (sessionId: string, on: boolean) => void
/**
* How to read the used/window numbers out of this agent's transcript. Defaults to claude's
* `parseLatestUsage`. gemini and codex pass their own (`core/gemini-session.ts`
@@ -443,6 +448,10 @@ export function createContextTail(
for (const id of parseToolResultIds(completeLines)) opts.onToolResult(sessionId, id)
if (opts?.onTurnInterrupted)
for (const id of t.interrupts.scan(completeLines)) opts.onTurnInterrupted(sessionId, id)
+ if (opts?.onRemoteControl) {
+ const rc = parseRemoteControl(completeLines)
+ if (rc !== null) opts.onRemoteControl(sessionId, rc)
+ }
}
}
diff --git a/src/core/remote-control-scan.test.ts b/src/core/remote-control-scan.test.ts
new file mode 100644
index 000000000..a8f5b9416
--- /dev/null
+++ b/src/core/remote-control-scan.test.ts
@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'vitest'
+import { parseRemoteControl, remoteControlHandler } from './remote-control-scan'
+
+const on = JSON.stringify({
+ type: 'system',
+ subtype: 'bridge_status',
+ content: '/remote-control is active · Continue here, on your phone, or at https://claude.ai/code/session_x',
+ url: 'https://claude.ai/code/session_x'
+})
+const off = JSON.stringify({
+ type: 'system',
+ subtype: 'local_command',
+ content: '<local-command-stdout>Remote Control disconnected.</local-command-stdout>',
+ commandRun: { command: 'remote-control', args: '' }
+})
+// MEASURED on 2.1.325: what `/remote-control` writes when its dialog is dismissed.
+const dismissed = JSON.stringify({
+ type: 'system',
+ subtype: 'local_command',
+ content: '<local-command-stdout></local-command-stdout>',
+ commandRun: { command: 'remote-control', args: '' }
+})
+
+describe('parseRemoteControl', () => {
+ it('reads a connect as on and a disconnect as off', () => {
+ expect(parseRemoteControl([on])).toBe(true)
+ expect(parseRemoteControl([off])).toBe(false)
+ })
+
+ it('lets the latest record win', () => {
+ expect(parseRemoteControl([on, off])).toBe(false)
+ expect(parseRemoteControl([off, on])).toBe(true)
+ expect(parseRemoteControl([on, off, on].join('\n'))).toBe(true)
+ })
+
+ it('says nothing when no record matches', () => {
+ expect(parseRemoteControl([])).toBeNull()
+ expect(parseRemoteControl([dismissed])).toBeNull()
+ expect(parseRemoteControl(['{"type":"user","message":{"content":"hi"}}'])).toBeNull()
+ })
+
+ it('never reads the words out of conversation text', () => {
+ // A user or assistant message that merely MENTIONS either marker is not a state change.
+ const chatter = [
+ JSON.stringify({ type: 'user', message: { content: 'what does bridge_status mean?' } }),
+ JSON.stringify({ type: 'assistant', message: { content: 'Remote Control disconnected.' } }),
+ JSON.stringify({ type: 'system', subtype: 'informational', content: 'Remote Control disconnected.' })
+ ]
+ expect(parseRemoteControl(chatter)).toBeNull()
+ expect(parseRemoteControl([on, ...chatter])).toBe(true)
+ })
+
+ it('skips torn and malformed lines', () => {
+ expect(parseRemoteControl([on.slice(0, 40), '', 'not json bridge_status'])).toBeNull()
+ expect(parseRemoteControl([on, off.slice(0, 50)])).toBe(true)
+ })
+})
+
+describe('remoteControlHandler', () => {
+ it('maps the session back to its node', () => {
+ const seen: unknown[] = []
+ const handler = remoteControlHandler(new Map([['n1', 's1'], ['n2', 's2']]), (u) => seen.push(u))
+ handler('s2', true)
+ handler('unknown', true)
+ expect(seen).toEqual([{ nodeId: 'n2', sessionId: 's2', on: true }])
+ })
+})
diff --git a/src/core/remote-control-scan.ts b/src/core/remote-control-scan.ts
new file mode 100644
index 000000000..0d5e88c2d
--- /dev/null
+++ b/src/core/remote-control-scan.ts
@@ -0,0 +1,76 @@
+/**
+ * Claude Code "Remote Control" (`/remote-control`, alias `/rc`): whether a session is currently
+ * reachable from claude.ai / the Claude mobile app, read from the session's own transcript.
+ *
+ * There is no hook for it, so the transcript is the only signal. Two records matter, and the
+ * LATEST one wins:
+ *
+ * - ON: `{"type":"system","subtype":"bridge_status","url":…}` — appended when the bridge
+ * connects ("/remote-control is active · Continue here, on your phone, or at <url>").
+ * - OFF: a `local_command` record whose stdout says "Remote Control disconnected" — what the
+ * command's "Disconnect this session" choice prints.
+ *
+ * WHAT IS MEASURED AND WHAT IS NOT (Claude Code 2.1.325). The `local_command` record SHAPE is
+ * measured: running `/remote-control` writes `subtype:"local_command"` records carrying
+ * `<local-command-stdout>…</local-command-stdout>`. The `bridge_status` record and the disconnect
+ * text are read out of the CLI's own source, NOT captured from a live connect — nobody has run a
+ * real connect/disconnect against this parser yet. So it degrades to nothing: a line that does not
+ * match exactly is ignored and the icon simply stays off. It can under-report; it never invents ON.
+ *
+ * Other ways the bridge ends (the CLI exits, the server drops it, org policy) write nothing we
+ * know of, which is why the renderer also clears the flag at a session boundary.
+ */
+
+const DISCONNECTED = 'Remote Control disconnected'
+
+/** The state the LAST matching record in `lines` asserts, or null when none does. Pure. */
+export function parseRemoteControl(text: string | string[]): boolean | null {
+ const lines = Array.isArray(text) ? text : text.split('\n')
+ let state: boolean | null = null
+ for (const line of lines) {
+ const s = line.trim()
+ // Cheap pre-filter: both records are `system` records naming one of two subtypes.
+ if (!s || (!s.includes('bridge_status') && !s.includes(DISCONNECTED))) continue
+ let o: { type?: unknown; subtype?: unknown; content?: unknown; url?: unknown }
+ try {
+ o = JSON.parse(s)
+ } catch {
+ continue
+ }
+ if (!o || o.type !== 'system') continue
+ if (o.subtype === 'bridge_status') {
+ state = true
+ } else if (
+ o.subtype === 'local_command' &&
+ typeof o.content === 'string' &&
+ o.content.includes('<local-command-stdout>') &&
+ o.content.includes(DISCONNECTED)
+ ) {
+ state = false
+ }
+ }
+ return state
+}
+
+/** What the shells broadcast on `agent:remote-control`. */
+export interface RemoteControlUpdate {
+ nodeId: string
+ sessionId: string
+ on: boolean
+}
+
+/**
+ * The context tails' `onRemoteControl` handler, shared by both shells so the desktop and the
+ * Server Edition cannot drift: map the tail's session id back to its node and broadcast.
+ * `nodeBySession` is each shell's own `nodeContextSession` (nodeId → sessionId).
+ */
+export function remoteControlHandler(
+ nodeContextSession: ReadonlyMap<string, string>,
+ broadcast: (update: RemoteControlUpdate) => void
+): (sessionId: string, on: boolean) => void {
+ return (sessionId, on) => {
+ for (const [nodeId, sid] of nodeContextSession) {
+ if (sid === sessionId) broadcast({ nodeId, sessionId, on })
+ }
+ }
+}
diff --git a/src/main/index.ts b/src/main/index.ts
index 19c50ff12..ec1a036bd 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -298,6 +298,7 @@ import { createCursorSubagentTracker } from '../core/cursor-subagents'
import { ClaudeSubagentLifecycle } from '../core/claude-subagent-lifecycle'
import { claudeSubagentTranscriptPath, isClaudeAgentId } from '../shared/agents/claude-subagents'
import { createContextTail, type TaskNotification } from '../core/context-tail'
+import { remoteControlHandler } from '../core/remote-control-scan'
import { registerContextEnsureIpc } from '../core/context-ensure'
import { grokContextParse, GROK_SIGNALS_FILE } from '../core/grok-signals'
import { applyCursorRaw, cursorContextParse, readCursorContextSource, releaseCursorRaw } from '../core/cursor-chat'
@@ -3072,7 +3073,12 @@ app.whenReady().then(async () => {
}
}
}
- const contextTail = createContextTail(pushContextUpdate, { onTaskNotification, onToolResult, onTurnInterrupted })
+ // Claude Remote Control on/off, read from the transcript (no hook exists). ONE handler for the
+ // local and the SSH tail; the Server Edition wires the same core helper.
+ const onRemoteControl = remoteControlHandler(nodeContextSession, (u) =>
+ corePlatform.broadcast(IPC.agentRemoteControl, u)
+ )
+ const contextTail = createContextTail(pushContextUpdate, { onTaskNotification, onToolResult, onTurnInterrupted, onRemoteControl })
// ONE TAIL PER AGENT, each with its own parser — not one tail switching on an agent id, which
// would mean changing `ContextTail.track(sessionId, path)` and the four call sites that depend on
// it. The poller (offset reads, torn-line carry, change-gated push) is written once in
@@ -3113,7 +3119,7 @@ app.whenReady().then(async () => {
const remoteFile = new RemoteFile((args) =>
sshProjectManager ? sshProjectManager.sshRun(args) : Promise.resolve({ code: 1, stdout: '' })
)
- const remoteContextTail = createRemoteContextTail(win, remoteFile, { onTaskNotification, onToolResult, onTurnInterrupted })
+ const remoteContextTail = createRemoteContextTail(win, remoteFile, { onTaskNotification, onToolResult, onTurnInterrupted, onRemoteControl })
const remoteCodexContextTail = createRemoteContextTail((usage) => {
const scoped = remoteCodexContext.publish(usage)
if (scoped) pushContextUpdate(scoped)
diff --git a/src/main/remote-context-tail.ts b/src/main/remote-context-tail.ts
index 0b2a52a3b..3cc8a9142 100644
--- a/src/main/remote-context-tail.ts
+++ b/src/main/remote-context-tail.ts
@@ -17,6 +17,7 @@ import {
type ContextTailOptions
} from '../core/context-tail'
import { splitCompleteLines } from '../core/subagent-tail'
+import { parseRemoteControl } from '../core/remote-control-scan'
import { ContextReadError, type RemoteFile, type RemoteFileRef } from './remote-ssh/remote-file'
const POLL_MS = 1000
@@ -134,6 +135,12 @@ export function createRemoteContextTail(
if (historical) t.interrupts.scan(completeLines, { record: true })
else if (opts?.onTurnInterrupted)
for (const id of t.interrupts.scan(eventLines)) opts.onTurnInterrupted(sessionId, id)
+ // Remote Control is a STATE (latest record wins), so a historical read reports it too —
+ // unlike the event scanners above, replaying it is correct, not a duplicate.
+ if (opts?.onRemoteControl) {
+ const rc = parseRemoteControl(completeLines)
+ if (rc !== null) opts.onRemoteControl(sessionId, rc)
+ }
}
const push = (sessionId: string, t: Tracked): void => {
diff --git a/src/preload/index.ts b/src/preload/index.ts
index c9e4ae539..c92d6dca9 100644
--- a/src/preload/index.ts
+++ b/src/preload/index.ts
@@ -664,6 +664,11 @@ const api: NodeTerminalApi = {
ipcRenderer.on(IPC.contextUpdate, handler)
return () => ipcRenderer.removeListener(IPC.contextUpdate, handler)
},
+ onRemoteControl: (listener) => {
+ const handler = (_e: unknown, payload: Parameters<typeof listener>[0]) => listener(payload)
+ ipcRenderer.on(IPC.agentRemoteControl, handler)
+ return () => ipcRenderer.removeListener(IPC.agentRemoteControl, handler)
+ },
ensure: (sessionId, cwd, accountId, nodeId, agentId) =>
ipcRenderer.send(IPC.contextEnsure, sessionId, cwd, accountId, nodeId, agentId)
},
diff --git a/src/renderer/bridge/ws-bridge.ts b/src/renderer/bridge/ws-bridge.ts
index 20ee8596e..9b9469613 100644
--- a/src/renderer/bridge/ws-bridge.ts
+++ b/src/renderer/bridge/ws-bridge.ts
@@ -752,6 +752,7 @@ export function buildFilesApi(
const context: ContextApi = {
onUpdate: (listener) => client.subscribe(IPC.contextUpdate, listener as Listener),
+ onRemoteControl: (listener) => client.subscribe(IPC.agentRemoteControl, listener as Listener),
ensure: (sessionId, cwd, accountId, nodeId, agentId) =>
client.cast(IPC.contextEnsure, sessionId, cwd, accountId, nodeId, agentId)
}
diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsx
index 3af4243da..f7bfff337 100644
--- a/src/renderer/canvas/Canvas.tsx
+++ b/src/renderer/canvas/Canvas.tsx
@@ -68,7 +68,7 @@ import {
wheelGestureReporting
} from './wheel-gesture'
import { isBrowserRuntime } from '@renderer/bridge/runtime'
-import { applyPhoneAccess } from '@renderer/lib/phoneAccess'
+import { useRemoteControl } from '@renderer/state/remoteControl'
import { WheelZoomBurstLimiter, clampWheelZoomSpeed, nextWheelZoom } from './wheel-zoom'
import { canCopyFilesToClipboard, selectedLocalFilePaths } from './canvas-file-copy'
import {
@@ -178,7 +178,6 @@ import {
IconPower,
IconProject,
IconRemote,
- IconRemoteAccess,
IconSave,
IconSearch,
IconSelectAll,
@@ -5268,6 +5267,11 @@ export function Canvas() {
return window.nodeTerminal.context.onUpdate((u) => useContextWindow.getState().set(u))
}, [])
+ // Claude Remote Control on/off per node (transcript-read in core) into its transient store.
+ useEffect(() => {
+ return window.nodeTerminal.context.onRemoteControl((u) => useRemoteControl.getState().set(u))
+ }, [])
+
// Prevent a stray file drop (outside a terminal body) from navigating the whole window to
// the dropped file. Terminal nodes handle their own drop and stopPropagation, so this only
// catches drops on empty canvas / other UI.
@@ -19978,24 +19982,6 @@ export function Canvas() {
>
<IconPhone />
</button>
- {/* Remote access on/off at a glance — green = the standing relay host is on, so a paired
- phone can reach this machine from anywhere. Same switch as the pair popover and
- Settings → Phone. Hidden on the Server Edition: there is no relay host to start there
- (the bridge's setPhoneAccess is a no-op), and a toggle that only changed colour would lie. */}
- {!isBrowserRuntime() && (
- <button
- className="cluster-remote"
- aria-pressed={settings.phoneAccessEnabled}
- title={
- settings.phoneAccessEnabled
- ? 'Remote access is on — click to turn off'
- : 'Remote access is off — click to turn on'
- }
- onClick={() => applyPhoneAccess(!settings.phoneAccessEnabled)}
- >
- <IconRemoteAccess />
- </button>
- )}
<button
title={commandTooltip('Settings', 'app.settings')}
onClick={() => {
diff --git a/src/renderer/components/RemoteControlButton.tsx b/src/renderer/components/RemoteControlButton.tsx
new file mode 100644
index 000000000..72bfe0798
--- /dev/null
+++ b/src/renderer/components/RemoteControlButton.tsx
@@ -0,0 +1,93 @@
+import { useState } from 'react'
+import type { AgentState } from '@shared/agents/normalize'
+import type { PtyApi } from '@shared/types'
+import { IconRemoteAccess } from './icons'
+import { Tooltip } from './Tooltip'
+import { remoteControlOn, useRemoteControl } from '../state/remoteControl'
+import { useSettings } from '../state/settings'
+import { isHidden } from '../lib/ui-visibility'
+import { remoteControlRefusal, toggleRemoteControl } from '../lib/remoteControlToggle'
+
+/**
+ * Claude Remote Control toggle — ONE component for the canvas node header and the kanban card
+ * modal (two views of the same session must not behave differently). Green while this session is
+ * reachable from claude.ai / the Claude app; a click runs `/remote-control` in the session.
+ *
+ * `write` is the caller's raw write to its LIVE pty view, used for the single pane-gated Enter that
+ * confirms a disconnect (lib/remoteControlToggle.ts). A caller without one passes nothing: Claude's
+ * own disconnect dialog then stays open in the terminal for the user to confirm.
+ */
+export function RemoteControlButton({
+ nodeId,
+ sessionId,
+ readState,
+ pty,
+ write,
+ className
+}: {
+ nodeId: string
+ /** The session this node's transcript readers look at (`transcriptSessionFor`). */
+ sessionId: string | null | undefined
+ /** The node's agent state, read at CLICK time. */
+ readState: () => AgentState | undefined
+ pty: Pick<PtyApi, 'sendText' | 'capture'>
+ write?: (data: string) => void
+ className: string
+}): JSX.Element | null {
+ // Hidden here, like the context meter, so the Settings switch covers both views at once.
+ const hidden = useSettings((s) => isHidden('remote-control', s.settings.hiddenHeaderButtons))
+ const entry = useRemoteControl((s) => s.byNode[nodeId])
+ const [busy, setBusy] = useState(false)
+ // Green only when the transcript of THIS node's current session says so; unknown reads as off.
+ const on = remoteControlOn(entry, sessionId)
+
+ const toast = (message: string): void => {
+ window.dispatchEvent(new CustomEvent('nodeterm:toast', { detail: { kind: 'error', message } }))
+ }
+
+ const onClick = async (): Promise<void> => {
+ // Re-read at click time: a prompt that appeared since the last render would be ANSWERED by
+ // the typed command.
+ const why = remoteControlRefusal(readState())
+ if (why) return toast(why)
+ setBusy(true)
+ try {
+ const result = await toggleRemoteControl(
+ {
+ sendText: (text) => pty.sendText(nodeId, text),
+ capture: () => pty.capture(nodeId),
+ write,
+ sleep: (ms) => new Promise((r) => setTimeout(r, ms))
+ },
+ on
+ )
+ if (result === 'undelivered') toast('Could not send /remote-control to this session.')
+ } finally {
+ setBusy(false)
+ }
+ }
+
+ if (hidden) return null
+ return (
+ <Tooltip
+ label={
+ on
+ ? 'Remote Control is on — reachable from claude.ai and the Claude app. Click to disconnect'
+ : 'Remote Control is off — click to reach this session from claude.ai or the Claude app'
+ }
+ >
+ <button
+ className={`${className} nodrag`}
+ aria-label="Claude Remote Control"
+ aria-pressed={on}
+ disabled={busy}
+ onClick={(e) => {
+ e.stopPropagation()
+ void onClick()
+ }}
+ >
+ <IconRemoteAccess />
+ </button>
+ </Tooltip>
+ )
+}
diff --git a/src/renderer/components/icons.tsx b/src/renderer/components/icons.tsx
index fea76379f..787c4f9ce 100644
--- a/src/renderer/components/icons.tsx
+++ b/src/renderer/components/icons.tsx
@@ -175,8 +175,8 @@ export const IconRemote = () => (
</svg>
)
-/** Remote access (phone relay) on/off — an antenna with signal arcs. Not `IconRemote` (the globe
- * already means "web view") and not `IconBroadcast` ("share live link"). */
+/** Claude Remote Control on/off in a terminal header — an antenna with signal arcs. Not
+ * `IconRemote` (the globe already means "web view") and not `IconBroadcast` ("share live link"). */
export const IconRemoteAccess = () => (
<svg {...S}>
<circle cx="12" cy="9" r="1.8" />
diff --git a/src/renderer/components/kanban/CardModal.tsx b/src/renderer/components/kanban/CardModal.tsx
index 4aa0a07f6..6c52984da 100644
--- a/src/renderer/components/kanban/CardModal.tsx
+++ b/src/renderer/components/kanban/CardModal.tsx
@@ -24,6 +24,7 @@ import { nodeIconDialog } from '../NodeIconPicker'
import { applyIconChoice } from '../../lib/nodeIconChoice'
import { normalizeNodeIcon, type NodeIcon } from '@shared/node-icon'
import { ContextMeter } from '../ContextMeter'
+import { RemoteControlButton } from '../RemoteControlButton'
import { isRemoteSessionNode } from '@shared/worktree'
import { AccountChip, useAccountChip } from '../AccountChip'
import { LiveLinkChip, projectSessionSource } from '../LiveLinkChip'
@@ -72,7 +73,7 @@ import { NoteMarkdown } from '../NoteMarkdown'
import { inLiveChatDrawer } from '../../lib/liveChatPin'
import { relativeTime } from '../../lib/relativeTime'
import { TerminalMarkdownView } from '../../nodes/TerminalMarkdownView'
-import { canChat } from '@shared/agents/config'
+import { canChat, canRemoteControl } from '@shared/agents/config'
import { transcriptSessionFor } from '../../lib/transcriptSession'
import { effectiveAccountId } from '../../lib/accountChip'
import { useSettings } from '../../state/settings'
@@ -259,6 +260,8 @@ export function CardModal({ session, projectId, projectName, projectColor, colum
const useChat = mdOpen && !!createdAgent && canChat(createdAgent) && !!transcript.sessionId
// Whether the ⌘M face is the chat panel, asked before it is open (the carry into the composer).
const chatFace = !!createdAgent && canChat(createdAgent) && !!transcript.sessionId
+ // Same gate as the node header: Claude only, and not on a relay tab (no local transcript tail).
+ const remoteControlShown = !!createdAgent && canRemoteControl(createdAgent) && coreSource !== 'relay'
const chatFaceRef = useRef(chatFace)
chatFaceRef.current = chatFace
const mdOpenRef = useRef(mdOpen)
@@ -644,6 +647,15 @@ export function CardModal({ session, projectId, projectName, projectColor, colum
<>
{/* Same context-window pill + popover as the node header (null until usage data). */}
<ContextMeter sessionId={transcript.sessionId ?? null} fromLaunchId={transcript.fallback} nodeId={session.id} remote={isRemoteSessionNode(session.spawn)} agentId={session.agentId ?? session.spawn.agentId ?? observedAgentId} />
+ {remoteControlShown && (
+ <RemoteControlButton
+ className="kanban-modal__action kanban-modal__remote-control"
+ nodeId={session.id}
+ sessionId={transcript.sessionId}
+ readState={() => agentStatusStore.getState().byId[session.id]?.state}
+ pty={api.pty}
+ />
+ )}
<button
className="kanban-modal__action"
title={commandTooltip(mdOpen ? 'Back to the live terminal' : 'Markdown / chat view', 'node.toggleMarkdown')}
diff --git a/src/renderer/lib/remoteControlToggle.test.ts b/src/renderer/lib/remoteControlToggle.test.ts
new file mode 100644
index 000000000..ece076253
--- /dev/null
+++ b/src/renderer/lib/remoteControlToggle.test.ts
@@ -0,0 +1,92 @@
+import { describe, expect, it, vi } from 'vitest'
+import {
+ DISCONNECT_POLL_ATTEMPTS,
+ REMOTE_CONTROL_COMMAND,
+ disconnectRowSelected,
+ remoteControlRefusal,
+ toggleRemoteControl,
+ type RemoteControlToggleDeps
+} from './remoteControlToggle'
+import { remoteControlOn } from '../state/remoteControl'
+
+const deps = (over: Partial<RemoteControlToggleDeps> = {}): RemoteControlToggleDeps & { write: ReturnType<typeof vi.fn> } => ({
+ sendText: vi.fn(async () => true as const),
+ capture: vi.fn(async () => ''),
+ write: vi.fn(),
+ sleep: vi.fn(async () => {}),
+ ...over
+}) as never
+
+const DISCONNECT_DIALOG = [' Remote Control', ' ❯ 1. Disconnect this session', ' 2. Show QR code', ' 3. Continue'].join('\n')
+// MEASURED on 2.1.325: the one-time consent dialog. Its first row must never get our Enter.
+const CONSENT_DIALOG = [' Remote Control', ' ❯ 1. Enable Remote Control Opens a secure connection to claude.ai.', ' 2. Never mind'].join('\n')
+
+describe('disconnectRowSelected', () => {
+ it('needs the cursor on the disconnect row', () => {
+ expect(disconnectRowSelected(DISCONNECT_DIALOG)).toBe(true)
+ expect(disconnectRowSelected(' ❯ Disconnect this session')).toBe(true)
+ expect(disconnectRowSelected(CONSENT_DIALOG)).toBe(false)
+ expect(disconnectRowSelected(' 1. Disconnect this session\n ❯ 3. Continue')).toBe(false)
+ expect(disconnectRowSelected('')).toBe(false)
+ })
+})
+
+describe('remoteControlRefusal', () => {
+ it('refuses only while a prompt owns the keyboard', () => {
+ expect(remoteControlRefusal('blocked')).toBeTruthy()
+ expect(remoteControlRefusal('waiting')).toBeTruthy()
+ expect(remoteControlRefusal('working')).toBeNull()
+ expect(remoteControlRefusal('done')).toBeNull()
+ expect(remoteControlRefusal(undefined)).toBeNull()
+ })
+})
+
+describe('toggleRemoteControl', () => {
+ it('turning on sends the command and presses nothing', async () => {
+ const d = deps()
+ expect(await toggleRemoteControl(d, false)).toBe('sent')
+ expect(d.sendText).toHaveBeenCalledWith(REMOTE_CONTROL_COMMAND)
+ expect(d.capture).not.toHaveBeenCalled()
+ expect(d.write).not.toHaveBeenCalled()
+ })
+
+ it('turning off confirms only once the disconnect row is on screen', async () => {
+ const capture = vi.fn().mockResolvedValueOnce('').mockResolvedValueOnce(DISCONNECT_DIALOG)
+ const d = deps({ capture })
+ expect(await toggleRemoteControl(d, true)).toBe('disconnected')
+ expect(d.write).toHaveBeenCalledTimes(1)
+ expect(d.write).toHaveBeenCalledWith('\r')
+ })
+
+ it('never presses Enter on a different dialog', async () => {
+ const d = deps({ capture: vi.fn(async () => CONSENT_DIALOG) })
+ expect(await toggleRemoteControl(d, true)).toBe('dialog-left-open')
+ expect(d.capture).toHaveBeenCalledTimes(DISCONNECT_POLL_ATTEMPTS)
+ expect(d.write).not.toHaveBeenCalled()
+ })
+
+ it('leaves the dialog to the user when the caller has no live write', async () => {
+ const d = deps({ write: undefined, capture: vi.fn(async () => DISCONNECT_DIALOG) })
+ expect(await toggleRemoteControl(d, true)).toBe('dialog-left-open')
+ expect(d.capture).not.toHaveBeenCalled()
+ })
+
+ it('survives a failing capture and an undelivered command', async () => {
+ const d = deps({ capture: vi.fn(async () => { throw new Error('gone') }) })
+ expect(await toggleRemoteControl(d, true)).toBe('dialog-left-open')
+ expect(d.write).not.toHaveBeenCalled()
+ const refused = deps({ sendText: vi.fn(async () => false as const) })
+ expect(await toggleRemoteControl(refused, true)).toBe('undelivered')
+ expect(refused.capture).not.toHaveBeenCalled()
+ })
+})
+
+describe('remoteControlOn', () => {
+ it('is on only for the node\'s current session', () => {
+ expect(remoteControlOn({ sessionId: 's1', on: true }, 's1')).toBe(true)
+ expect(remoteControlOn({ sessionId: 's1', on: false }, 's1')).toBe(false)
+ expect(remoteControlOn({ sessionId: 's1', on: true }, 's2')).toBe(false)
+ expect(remoteControlOn({ sessionId: 's1', on: true }, null)).toBe(false)
+ expect(remoteControlOn(undefined, 's1')).toBe(false)
+ })
+})
diff --git a/src/renderer/lib/remoteControlToggle.ts b/src/renderer/lib/remoteControlToggle.ts
new file mode 100644
index 000000000..4c167e809
--- /dev/null
+++ b/src/renderer/lib/remoteControlToggle.ts
@@ -0,0 +1,82 @@
+import type { AgentState } from '@shared/agents/normalize'
+import type { TextDeliveryResult } from '@shared/text-delivery'
+
+/**
+ * The header's Remote Control button, as a pure plan + a small runner.
+ *
+ * Claude Code has ONE command for both directions (`/remote-control`, measured on 2.1.325):
+ * - while OFF it connects (the first time ever it asks "Enable Remote Control?" in the terminal —
+ * that consent is the user's to give, so we never answer it);
+ * - while ON it opens a dialog whose first row is "Disconnect this session".
+ *
+ * So turning it OFF needs an Enter on that dialog. We press it ONLY after reading the pane and
+ * seeing the selection cursor on that exact row. Anything else on screen (the consent dialog,
+ * whose first row is "Enable Remote Control"; a permission prompt; a dialog drawn differently
+ * by a newer CLI) gets no key from us — the dialog simply stays open for the user to answer.
+ * The dialog's row text comes from the CLI's source; its live rendering has not been captured,
+ * which is exactly why the Enter is gated on what the pane shows rather than on a timer.
+ */
+export const REMOTE_CONTROL_COMMAND = '/remote-control'
+
+/** True when the pane shows the disconnect dialog with the cursor on "Disconnect this session". */
+export function disconnectRowSelected(paneText: string): boolean {
+ return paneText.split('\n').some((line) => /❯\s*(\d+\.\s*)?Disconnect this session/.test(line))
+}
+
+/**
+ * Why the button must not type right now, or null. A command typed into a permission prompt or a
+ * question ANSWERS it (same rule as the in-place restart). A working session is fine: the command
+ * is one Claude runs immediately, mid-turn.
+ */
+export function remoteControlRefusal(state: AgentState | undefined): string | null {
+ if (state === 'blocked' || state === 'waiting')
+ return 'Claude is waiting for your answer — respond in the terminal first, then toggle Remote Control.'
+ return null
+}
+
+export interface RemoteControlToggleDeps {
+ sendText(text: string): Promise<TextDeliveryResult>
+ /** The pane's visible text. */
+ capture(): Promise<string>
+ /** Write raw bytes to the live pty (only used for the gated Enter). Absent ⇒ the disconnect
+ * dialog is left open for the user. */
+ write?: (data: string) => void
+ sleep(ms: number): Promise<void>
+}
+
+export type RemoteControlToggleResult =
+ /** The command was delivered; Claude connects (or asks its one-time consent in the terminal). */
+ | 'sent'
+ /** Disconnect dialog seen and confirmed. */
+ | 'disconnected'
+ /** Command delivered but the disconnect row was not seen — the dialog is left for the user. */
+ | 'dialog-left-open'
+ /** Nothing could be written (session unavailable). */
+ | 'undelivered'
+
+export const DISCONNECT_POLL_MS = 250
+export const DISCONNECT_POLL_ATTEMPTS = 12
+
+export async function toggleRemoteControl(
+ deps: RemoteControlToggleDeps,
+ currentlyOn: boolean
+): Promise<RemoteControlToggleResult> {
+ const delivered = await deps.sendText(REMOTE_CONTROL_COMMAND)
+ if (delivered !== true) return 'undelivered'
+ if (!currentlyOn) return 'sent'
+ if (!deps.write) return 'dialog-left-open'
+ for (let i = 0; i < DISCONNECT_POLL_ATTEMPTS; i++) {
+ await deps.sleep(DISCONNECT_POLL_MS)
+ let pane = ''
+ try {
+ pane = await deps.capture()
+ } catch {
+ continue
+ }
+ if (disconnectRowSelected(pane)) {
+ deps.write('\r')
+ return 'disconnected'
+ }
+ }
+ return 'dialog-left-open'
+}
diff --git a/src/renderer/lib/ui-visibility.test.ts b/src/renderer/lib/ui-visibility.test.ts
index 4906a34ba..024fb7566 100644
--- a/src/renderer/lib/ui-visibility.test.ts
+++ b/src/renderer/lib/ui-visibility.test.ts
@@ -31,7 +31,7 @@ describe('hideable inventories', () => {
'markdown-view', 'refresh-terminal', 'live-link', 'vanilla-restart'
])
expect(HIDEABLE_HEADER_BUTTONS.map((r) => r.id)).toEqual([
- 'context-meter', 'maximize', 'refresh', 'mic', 'ai-name', 'comments', 'share-link', 'hide-fanout', 'tidy-fanout', 'md-hint'
+ 'context-meter', 'remote-control', 'maximize', 'refresh', 'mic', 'ai-name', 'comments', 'share-link', 'hide-fanout', 'tidy-fanout', 'md-hint'
])
})
it('gives every entry a user-facing label', () => {
diff --git a/src/renderer/lib/ui-visibility.ts b/src/renderer/lib/ui-visibility.ts
index 290d865f5..4bc1be4d5 100644
--- a/src/renderer/lib/ui-visibility.ts
+++ b/src/renderer/lib/ui-visibility.ts
@@ -40,6 +40,7 @@ export const HIDEABLE_HEADER_BUTTONS: readonly HideableRow[] = [
// itself, so it hides on all three places the pill is drawn: node header, kanban card, card
// modal. Display only — usage tracking and the ⌘M composer's model label are unaffected.
{ id: 'context-meter', label: 'Model & context meter' },
+ { id: 'remote-control', label: 'Claude Remote Control' },
{ id: 'maximize', label: 'Maximize' },
{ id: 'refresh', label: 'Refresh' },
{ id: 'mic', label: 'Dictate' },
diff --git a/src/renderer/nodes/TerminalNode.tsx b/src/renderer/nodes/TerminalNode.tsx
index f4e7d79dc..67c767cac 100644
--- a/src/renderer/nodes/TerminalNode.tsx
+++ b/src/renderer/nodes/TerminalNode.tsx
@@ -255,6 +255,7 @@ import { pasteWithImageReceipt } from '../terminal/image-paste-confirm'
import { usePasteReceipt } from '../terminal/usePasteReceipt'
import { createBoardPauseSlot } from '../terminal/board-render-pause'
import { ContextMeter } from '../components/ContextMeter'
+import { RemoteControlButton } from '../components/RemoteControlButton'
import { isZoomModifierHeld } from '../lib/zoomModifier'
import { HoverGuard } from './HoverGuard'
import {
@@ -322,6 +323,7 @@ import {
canChat,
canResume,
canRename,
+ canRemoteControl,
canReadTitle,
createdAgentId,
reportsOwnCopy,
@@ -1842,12 +1844,16 @@ export function TerminalNode({
const contextLinkCapable = !!agentId && canContextLink(agentId) // context-link tip wording only; handles render on all terminals
const showUsage = !!agentId && hasUsage(agentId) // per-node context-window meter
const showChat = !!agentId && canChat(agentId) // Cmd+M opens a chat panel instead of markdown
+ // Claude Remote Control toggle (header, right of the context meter). Not on a relay tab: the
+ // on/off signal is this machine's transcript tail, which never sees a guest core's session.
+ const showRemoteControl = !!agentId && canRemoteControl(agentId) && session.source !== 'relay'
// Everything that reads the conversation through CLAUDE's transcript readers (`context.ensure`'s
// mount-time meter rehydration, the find bar's transcript index) — deliberately NOT `showUsage`,
// which now spans three agents. See lib/transcriptGates.ts for what sharing that gate broke.
const claudeTranscript = readsClaudeTranscript(agentId)
// The header 💬 now opens the board-log comments flyout (right side); ⌘M keeps the markdown/chat view.
const [commentsOpen, setCommentsOpen] = useState(false)
+ const rawWriteRef = useRef<((data: string) => void) | null>(null)
const canRenameNode = !!agentId && canRename(agentId) // WRITE leg: push `/rename <name>` back
// READ leg: adopt the agent's own session name into the title. A superset of canRenameNode —
// gemini names its own sessions but has no rename command, so it polls and never pushes.
@@ -4511,6 +4517,9 @@ export function TerminalNode({
},
onData: (cb) => (sessionId && !life.dead ? transport.onData(sessionId, cb) : () => {})
}
+ // Published for the header's Remote Control toggle (its one gated Enter). Never cleared: the
+ // write is already a no-op once this session is dead, and the next lifecycle run replaces it.
+ rawWriteRef.current = restartIo.write
// The wake buffer flushes held keystrokes through the SAME session-scoped, lifetime-gated write
// as the resume line — so a flush into a torn-down session no-ops instead of throwing. Published
// to the ref the wake `.then` (component body) reads; re-set on every mount, which is when a new
@@ -6406,6 +6415,16 @@ export function TerminalNode({
</span>
) : null}
{showUsage && <ContextMeter sessionId={transcript.sessionId ?? null} fromLaunchId={transcript.fallback} nodeId={id} remote={!!remoteSession} agentId={agentId} />}
+ {showRemoteControl && (
+ <RemoteControlButton
+ className="term-node__remote-control"
+ nodeId={id}
+ sessionId={transcript.sessionId}
+ readState={() => agentStatusStore.getState().byId[id]?.state}
+ pty={session.api.pty}
+ write={(d) => rawWriteRef.current?.(d)}
+ />
+ )}
{/* Who else is in this node. Subscribes to presence itself — see PresenceChips. */}
<PresenceChips nodeId={id} />
{/* This terminal is broadcast by a live link — never hideable (live-link.guard.test.ts).
diff --git a/src/renderer/state/remoteControl.ts b/src/renderer/state/remoteControl.ts
new file mode 100644
index 000000000..55db1c5f0
--- /dev/null
+++ b/src/renderer/state/remoteControl.ts
@@ -0,0 +1,30 @@
+import { create } from 'zustand'
+
+/**
+ * Claude Remote Control on/off per node — TRANSIENT, never persisted. Fed by core's transcript
+ * tails over `context.onRemoteControl` (see core/remote-control-scan.ts for what is and is not
+ * measured about that signal). Keyed by node, stamped with the session it was read from, so a
+ * node that moves to another conversation does not inherit the old one's state.
+ */
+interface RemoteControlStore {
+ byNode: Record<string, { sessionId: string; on: boolean }>
+ set(update: { nodeId: string; sessionId: string; on: boolean }): void
+}
+
+export const useRemoteControl = create<RemoteControlStore>((set) => ({
+ byNode: {},
+ set: ({ nodeId, sessionId, on }) =>
+ set((s) => {
+ const cur = s.byNode[nodeId]
+ if (cur && cur.sessionId === sessionId && cur.on === on) return s
+ return { byNode: { ...s.byNode, [nodeId]: { sessionId, on } } }
+ })
+}))
+
+/** Is Remote Control known to be ON for this node's CURRENT session? Unknown reads as off. */
+export function remoteControlOn(
+ entry: { sessionId: string; on: boolean } | undefined,
+ currentSessionId: string | null | undefined
+): boolean {
+ return !!entry && entry.on && !!currentSessionId && entry.sessionId === currentSessionId
+}
diff --git a/src/renderer/styles.css b/src/renderer/styles.css
index f1c6c6623..5d3dc3f62 100644
--- a/src/renderer/styles.css
+++ b/src/renderer/styles.css
@@ -2509,6 +2509,7 @@ body,
.term-node__mic,
.term-node__search,
.term-node__refresh,
+.term-node__remote-control,
.term-node__external,
.term-node__maximize,
.term-node__close,
@@ -2540,6 +2541,7 @@ body,
.term-node__mic:hover,
.term-node__search:hover,
.term-node__refresh:hover,
+.term-node__remote-control:hover:not(:disabled),
.term-node__external:hover,
.term-node__maximize:hover,
.term-node__move-worktree:hover,
@@ -2575,6 +2577,16 @@ body,
+/* Claude Remote Control: green while the session is reachable from another device. */
+.term-node__remote-control[aria-pressed='true'],
+.kanban-modal__remote-control[aria-pressed='true'] {
+ color: var(--success);
+}
+.term-node__remote-control:disabled {
+ opacity: 0.6;
+ cursor: default;
+}
+
.term-node__hide-fanout[aria-pressed='true'] {
color: var(--accent-text);
}
@@ -6223,15 +6235,6 @@ body,
height: 18px;
}
-/* Remote-access toggle: green while the standing relay host is on, muted while off. */
-.controls-cluster > button.cluster-remote {
- color: var(--muted);
-}
-.controls-cluster > button.cluster-remote[aria-pressed='true'] {
- color: var(--success);
- border-color: color-mix(in srgb, var(--success) 45%, transparent);
-}
-
/* Search button shows the ⌘K shortcut so its purpose is obvious */
.cluster-search {
width: auto !important;
diff --git a/src/renderer/terminal/useContextEnsure.test.tsx b/src/renderer/terminal/useContextEnsure.test.tsx
index 3af15a886..2cdf53034 100644
--- a/src/renderer/terminal/useContextEnsure.test.tsx
+++ b/src/renderer/terminal/useContextEnsure.test.tsx
@@ -13,7 +13,7 @@ function Probe({ api, node = 'canvas', sid = 's1', account = 'a', agent = 'codex
return null
}
it('rehydrates canvas/modal mounts and changed node, account, session and core identities', async () => {
- const first = { ensure: vi.fn(), onUpdate: vi.fn() }, second = { ensure: vi.fn(), onUpdate: vi.fn() }
+ const first = { ensure: vi.fn(), onUpdate: vi.fn(), onRemoteControl: vi.fn() }, second = { ensure: vi.fn(), onUpdate: vi.fn(), onRemoteControl: vi.fn() }
const local = vi.fn()
Object.defineProperty(window, 'nodeTerminal', { configurable: true, value: { context: { ensure: local } } })
const root = createRoot(document.createElement('div'))
@@ -33,7 +33,7 @@ it('rehydrates canvas/modal mounts and changed node, account, session and core i
} finally { await act(async () => root.unmount()) }
})
it('does not ask for an unknown session or unsupported agent; keeps Claude routing', async () => {
- const api = { ensure: vi.fn(), onUpdate: vi.fn() }
+ const api = { ensure: vi.fn(), onUpdate: vi.fn(), onRemoteControl: vi.fn() }
const root = createRoot(document.createElement('div'))
try {
await act(async () => root.render(<Probe api={api} sid="" />))
diff --git a/src/server/agent-status.ts b/src/server/agent-status.ts
index 316b8a448..61f7bd2da 100644
--- a/src/server/agent-status.ts
+++ b/src/server/agent-status.ts
@@ -19,6 +19,7 @@ import { createCursorSubagentTracker } from '../core/cursor-subagents'
import { ClaudeSubagentLifecycle } from '../core/claude-subagent-lifecycle'
import { claudeSubagentTranscriptPath, isClaudeAgentId } from '../shared/agents/claude-subagents'
import { createContextTail, type ContextTail, type TaskNotification } from '../core/context-tail'
+import { remoteControlHandler } from '../core/remote-control-scan'
import { geminiContextParse } from '../core/gemini-session'
import { antigravityContextParse, rememberAntigravityModel } from '../core/antigravity-session'
import { codexContextParse } from '../core/codex-session'
@@ -172,8 +173,13 @@ export function wireAgentStatus(
}
}
}
+ // Claude Remote Control on/off, read from the transcript — same core helper as the desktop.
+ const onRemoteControl = remoteControlHandler(nodeContextSession, (u) =>
+ platform.broadcast(IPC.agentRemoteControl, u)
+ )
const contextTail =
- opts.contextTail ?? createContextTail(pushContextUpdate, { onTaskNotification, onToolResult, onTurnInterrupted })
+ opts.contextTail ??
+ createContextTail(pushContextUpdate, { onTaskNotification, onToolResult, onTurnInterrupted, onRemoteControl })
// ONE TAIL PER AGENT, each with its own parser — not one tail switching on an agent id, which
// would mean changing `ContextTail.track(sessionId, path)` and the four call sites that depend on
// it. The poller (offset reads, torn-line carry, change-gated push) is written once in
diff --git a/src/shared/agents/config.ts b/src/shared/agents/config.ts
index a3f68cdfa..96a9b830c 100644
--- a/src/shared/agents/config.ts
+++ b/src/shared/agents/config.ts
@@ -506,6 +506,11 @@ export const LINKED_CONTEXT_SKILL_AGENTS = ['claude', 'cursor'] as const
// rename command, so it stays out of RENAME_CAPABLE — the read⊇write invariant holds either way.
// cursor: its `name` (AI-generated, or `/rename`) is in the chat store meta; the write leg joined
// RENAME_CAPABLE once `/rename` was measured to land there.
+// Agents with an in-session "reach this session from another device" toggle the node header can
+// drive. claude only: `/remote-control` (alias `/rc`, measured on 2.1.325) connects the session to
+// claude.ai / the Claude mobile app and, run again, offers to disconnect it. State is read from
+// the transcript (core/remote-control-scan.ts). No other builtin has a measured equivalent.
+export const REMOTE_CONTROL_CAPABLE = ['claude'] as const
export const TITLE_READ_CAPABLE = ['claude', 'codex', 'grok', 'gemini', 'cursor'] as const
// Agents whose canvas nodes share ONE managed CLI server per machine and keep a stable per-node
// identity inside it, instead of each node owning a whole process tree.
@@ -741,6 +746,7 @@ export const reportsSessionEnd = (id: AgentId): boolean => includes(SESSION_END_
export const canRename = (id: AgentId): boolean => includes(RENAME_CAPABLE, id)
export const submitsSeparately = (id: AgentId): boolean => includes(SEPARATE_SUBMIT_AGENTS, id)
export const readsLinkedContextSkill = (id: AgentId): boolean => includes(LINKED_CONTEXT_SKILL_AGENTS, id)
+export const canRemoteControl = (id: AgentId): boolean => includes(REMOTE_CONTROL_CAPABLE, id)
export const canReadTitle = (id: AgentId): boolean => includes(TITLE_READ_CAPABLE, id)
export const canControlCanvas = (id: AgentId): boolean => includes(CANVAS_CONTROL_CAPABLE, id)
export const usesPosixToolShellOnWindows = (id: AgentId): boolean => includes(POSIX_TOOL_SHELL_ON_WINDOWS, id)
diff --git a/src/shared/ipc.ts b/src/shared/ipc.ts
index 8ce07e5f2..1d474fc85 100644
--- a/src/shared/ipc.ts
+++ b/src/shared/ipc.ts
@@ -454,6 +454,8 @@ export const IPC = {
triggersStatus: 'triggers:status',
triggersRunNow: 'triggers:run-now',
contextUpdate: 'context:update',
+ /** core → renderer: a Claude session's Remote Control connected/disconnected (transcript-read). */
+ agentRemoteControl: 'agent:remote-control',
contextEnsure: 'context:ensure',
// Team presence (docs/team-presence.md). `presence:hello` is a REQUEST: its response tells the
// client its own clientId, so it never draws its own cursor. The rest are casts (client→server)
diff --git a/src/shared/types.ts b/src/shared/types.ts
index 5e0d0baef..337e182a6 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -3589,6 +3589,11 @@ export interface ContextWindowUsage {
export interface ContextApi {
/** Fires whenever a session's context fill changes. Returns unsubscribe. */
onUpdate(listener: (usage: ContextWindowUsage) => void): () => void
+ /**
+ * Fires when a Claude session's transcript records Remote Control (`/remote-control`) connecting
+ * or disconnecting. Fed by the same transcript tails as `onUpdate`. Returns unsubscribe.
+ */
+ onRemoteControl(listener: (update: { nodeId: string; sessionId: string; on: boolean }) => void): () => void
/**
* Ask the core to start (or refresh) tracking a session's transcript so the meter populates
* without waiting for a live hook event — e.g. on node mount after an app restart, when