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.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
/**
* Does Claude Code's own UI own the keyboard right now? Read from the pane's SCREEN, because the
* dialogs that matter here fire no hook: the folder-trust prompt, `/model`, one-time setup questions.
* The agent state keeps reading idle (or working) while one is up, so the ⌘M chat view would type into
* it — the text is swallowed and the Enter answers the dialog. On the trust prompt the highlighted
* default is "No, exit".
*
* MEASURED on Claude Code 2.1.283 (fullscreen TUI, which nodeterm enables):
* - At its prompt — idle, or working with the queue open — the bottom of the screen is the input
* box: a `────` rule, a line starting `❯ ` at column 0 (continuation lines under it), another rule,
* then the status lines. In shell mode (a draft starting `!`) the prompt character is `!` instead
* (2.1.284; `#`, `&` and `@` drafts keep `❯`).
* - The trust prompt and the `/model` picker REPLACE that box, and end in a key-hint footer
* ("Enter to confirm · Esc to cancel", "… · s to use this session only · Esc to cancel").
* - A setup dialog seen in the field took the Enter while the typed text landed in the input box, so
* a dialog can also sit ABOVE a visible box. The footer alone is therefore enough to say "dialog".
*
* Only the BOTTOM of the capture is read: callers capture ~200 lines, history included, and a CLI
* not in fullscreen mode leaves old dialogs and old input boxes in that history. The live box must
* end within `BOX_TAIL_LINES` of the bottom, and a footer counts only in the last `FOOTER_TAIL_LINES`
* lines, or at most `FOOTER_ABOVE_BOX_LINES` above the box — never further up the history.
*
* Only `prompt` means "safe to type". `unknown` (nothing readable) is left to the caller; a screen
* with text but no input box and no footer is `no-prompt` — not necessarily a dialog (the CLI may be
* starting, or gone and a shell owns the pane), but still no place to type a prompt.
*/
export type ClaudeScreen =
| { kind: 'prompt' }
| { kind: 'dialog'; text: string }
| { kind: 'no-prompt' }
| { kind: 'unknown' }
// eslint-disable-next-line no-control-regex
const ANSI = /\x1b\[[0-?]*[ -/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g
/** A full-width rule of the input box (`─`, U+2500). */
const isRule = (line: string): boolean => /^─{20,}/.test(line.trim())
/** Any border a dialog is drawn under: the rule, or the `▔` top edge the `/model` picker uses. A
* label or notice can be painted over part of it (measured: "● high · /effort", a tmux notice),
* so it only has to START or END with the border characters. */
const isBorder = (line: string): boolean => /^\s*[─▔]{3,}/.test(line) || /[─▔]$/.test(line)
/** A key-hint footer. Capitalized on purpose: the working spinner says "esc to interrupt". */
const isFooter = (line: string): boolean => {
const t = line.trim()
return /^Enter to confirm\b/.test(t) || /(?:^|\s·\s)Esc to (?:cancel|exit|go back)$/.test(t)
}
/** Non-blank lines allowed under the box's bottom rule — the status lines (a custom statusline can
* take several). The agent list below them does not count (`isAgentListLine`). */
const BOX_TAIL_LINES = 8
/** At most this many agent-list lines are skipped, so an old box far up the history still is not
* taken for the live one. */
const AGENT_LIST_MAX_LINES = 40
/**
* A line of the agent list Claude Code draws UNDER its status lines while background agents or
* teammates run (MEASURED on 2.1.319, field screenshot + binary): one row per agent, starting with its
* status dot — `● main` for the one in view, `○ <name> <task> <state>` for the rest — and, when the
* list is longer than the space it gets, an overflow line `↓ 3 more` (`↑ 2 more · ↓ 3 more` once
* scrolled). With a few agents it pushed the input box past `BOX_TAIL_LINES` and the ⌘M view read the
* screen as having no input box.
*/
const isAgentListLine = (line: string): boolean => {
const t = line.trim()
return /^[●○] \S/.test(t) || /^(?:↑ \d+ more(?: · ↓ \d+ more)?|↓ \d+ more)$/.test(t)
}
/** A footer with no box: a dialog's key hints are its last line (measured: trust prompt, /model). */
const FOOTER_TAIL_LINES = 3
/** A footer above a live box: a dialog drawn right on top of the input box. */
const FOOTER_ABOVE_BOX_LINES = 4
/** The input box's first line: the `❯` prompt, or `!` in shell mode — followed by a NO-BREAK SPACE
* (U+00A0) there, measured, which `\s` covers. */
const isPromptLine = (line: string | undefined): boolean =>
line !== undefined && (line.startsWith('❯') || /^!(\s|$)/.test(line))
/** Indexes of the non-blank lines, bottom first. */
const nonBlankFromBottom = (lines: readonly string[]): number[] =>
lines.flatMap((l, i) => (l.trim() === '' ? [] : [i])).reverse()
/** The live input box: `[top rule, bottom rule]` line indexes, or null. */
function inputBox(lines: readonly string[]): [number, number] | null {
// The bottom lines a box may end on: the first BOX_TAIL_LINES + 1 non-blank lines from the bottom,
// not counting the agent list's lines (up to AGENT_LIST_MAX_LINES of them).
const tail: number[] = []
let listLines = 0
for (const i of nonBlankFromBottom(lines)) {
if (tail.length > BOX_TAIL_LINES) break
if (isAgentListLine(lines[i]) && listLines < AGENT_LIST_MAX_LINES) {
listLines++
continue
}
tail.push(i)
}
for (const bottom of tail) {
if (bottom === 0 || !isRule(lines[bottom])) continue
for (let top = bottom - 1; top >= 0 && bottom - top <= 40; top--) {
if (!isRule(lines[top])) continue
return isPromptLine(lines[top + 1]) && top + 1 < bottom ? [top, bottom] : null
}
return null
}
return null
}
/** The dialog's own lines: from the border above the footer down to the footer, dedented. */
function dialogText(lines: readonly string[], footer: number): string {
let start = footer
while (start > 0 && footer - start < 30 && !isBorder(lines[start - 1])) start--
const body = lines.slice(start, footer + 1).filter((l) => l.trim() !== '')
const indent = Math.min(...body.map((l) => l.length - l.trimStart().length))
return body.map((l) => l.slice(indent)).join('\n')
}
export function readClaudeScreen(screen: string): ClaudeScreen {
const lines = screen.replace(ANSI, '').split(/\r?\n/).map((l) => l.trimEnd())
if (lines.every((l) => l === '')) return { kind: 'unknown' }
const box = inputBox(lines)
const bottom = nonBlankFromBottom(lines)
// Where a footer may be: under the box (or at the very bottom when there is no box), and right
// above the box. Never inside it — a footer there is the user's own draft.
const candidates = box
? [
...bottom.filter((i) => i > box[1]),
...bottom.filter((i) => i < box[0]).slice(0, FOOTER_ABOVE_BOX_LINES)
]
: bottom.slice(0, FOOTER_TAIL_LINES)
const footer = candidates.find((i) => isFooter(lines[i]))
if (footer !== undefined) return { kind: 'dialog', text: dialogText(lines, footer) }
return box ? { kind: 'prompt' } : { kind: 'no-prompt' }
}
/** What the ⌘M chat view's screen poll learns from one read of the pane (`pty.readChatScreen`): who
* owns the keyboard, and the suggested next prompt, if any. */
export interface ChatScreenRead {
screen: ClaudeScreen
suggestion: string | null
}
/** Refuse to type: anything but a visible input box, except a screen we could not read at all. */
export function claudeScreenBlocksInput(s: ClaudeScreen): boolean {
return s.kind === 'dialog' || s.kind === 'no-prompt'
}
/**
* Is Claude Code's composer EMPTY right now? Read from a STYLED capture (`capture-pane -e`): the one
* fact the plain text cannot carry is the placeholder. MEASURED on Claude Code 2.1.301 (fullscreen
* TUI, fixtures in `__fixtures__/claude/composer-capture.json`): an empty composer reads
* `❯ Try "fix typecheck errors"` with the suggestion drawn SGR 2 (dim); a typed draft is the same
* line in the default style. Shell mode (`!`) is a draft even with a dim placeholder after it — the
* mode itself was typed, and text sent there runs as a shell command. A multi-line draft fills the
* lines under the prompt line.
*
* Exists for issue #1144: the context-link discovery note was pasted + Enter'd into a composer that
* already held the user's half-typed text, and both were submitted as one prompt.
*
* - `empty` — a live input box whose prompt line holds nothing but dim text (or nothing at all).
* - `draft` — anything typed into it.
* - `no-prompt` — a dialog owns the keyboard, or no input box is on screen (see `readClaudeScreen`).
* - `unknown` — nothing readable (a failed or empty capture).
*
* The error is asymmetric on purpose: only dim text counts as placeholder, so a capture that lost
* its SGR (or a CLI that styles the placeholder differently) reads `draft` and the caller does NOT
* type — the safe direction.
*/
export type ClaudeComposer = 'empty' | 'draft' | 'no-prompt' | 'unknown'
/** Does any visible, non-blank character of this styled line (from `from`, a plain-text column)
* sit outside SGR dim? */
function hasUndimmedText(styled: string, from: number): boolean {
return undimmedText(styled, from).trim() !== ''
}
/** The characters of this styled line (from `from`, a plain-text column) drawn outside SGR dim, in
* order. Walks the SGR state; non-SGR escapes are skipped. */
function undimmedText(styled: string, from: number): string {
let dim = false
let col = 0
let out = ''
let i = 0
while (i < styled.length) {
if (styled[i] === '\x1b') {
const csi = /^\x1b\[([0-?]*)([ -/]*)([@-~])/.exec(styled.slice(i))
if (csi) {
if (csi[3] === 'm') dim = applySgrDim(csi[1], dim)
i += csi[0].length
continue
}
// eslint-disable-next-line no-control-regex
const osc = /^\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/.exec(styled.slice(i))
i += osc ? osc[0].length : 1
continue
}
const ch = String.fromCodePoint(styled.codePointAt(i)!)
if (col >= from && !dim) out += ch
col += ch.length
i += ch.length
}
return out
}
/** The dim flag after one SGR sequence's parameters. Extended colours (`38;5;n`, `38;2;r;g;b`, and
* the 48/58 forms) consume their arguments, so the `2` in `38;2;…` is never read as dim. */
function applySgrDim(params: string, dim: boolean): boolean {
const ps = params === '' ? ['0'] : params.split(/[;:]/)
for (let k = 0; k < ps.length; k++) {
const p = ps[k] === '' ? 0 : Number(ps[k])
if (p === 38 || p === 48 || p === 58) {
const mode = Number(ps[k + 1])
k += mode === 5 ? 2 : mode === 2 ? 4 : 1
} else if (p === 0 || p === 22) dim = false
else if (p === 2) dim = true
}
return dim
}
export function readClaudeComposer(styledScreen: string): ClaudeComposer {
const styled = styledScreen.split(/\r?\n/)
const lines = styled.map((l) => l.replace(ANSI, '').trimEnd())
if (lines.every((l) => l === '')) return 'unknown'
if (readClaudeScreen(styledScreen).kind !== 'prompt') return 'no-prompt'
const box = inputBox(lines)
if (!box) return 'no-prompt'
const promptAt = box[0] + 1
const prompt = lines[promptAt]
if (!prompt.startsWith('❯')) return 'draft'
for (let i = promptAt + 1; i < box[1]; i++) if (lines[i].trim() !== '') return 'draft'
return hasUndimmedText(styled[promptAt], 1) ? 'draft' : 'empty'
}
/**
* What the user's draft in Claude Code's composer says, read from a STYLED capture, with all
* whitespace removed: the undimmed text of every line in the live input box, minus the `❯` prompt
* character. Shell mode's `!` is kept, since it was typed. The dim placeholder is not part of it, so
* an empty composer reads `''`. null when there is no live input box to read (a dialog, no box, a
* draft too tall for the box reader, an empty capture).
*
* Exists so the typed chat send can see that ITS text reached the composer. Counting the text across
* the whole screen fails for a short answer: typing also clears the placeholder and shortens the
* status line ("· ? for shortcuts · ← for agents" goes away), so the letter `a` typed in answer to a
* multiple-choice question appeared once more in the box and once less elsewhere. The count never
* rose, and the Enter was withheld with the text sitting in the box.
*
* Without SGR (a capture that lost it), the placeholder reads as draft text. Callers compare against
* the draft read before typing, so that only costs a match when the placeholder ends the same way.
*/
export function readClaudeDraft(styledScreen: string): string | null {
return readClaudeDraftBox(styledScreen)?.draft ?? null
}
/**
* `readClaudeDraft` plus how many screen rows the input box shows. MEASURED on Claude Code 2.1.319:
* a long line wraps onto several rows, and the box stops growing at about half the pane's height
* (7 rows at 24, 15 at 40, 25 at 60) and scrolls, showing the end of the draft with the caret there.
* So `draft` can be only the tail of what the box holds, and `rows` only what is on screen.
*/
export function readClaudeDraftBox(styledScreen: string): { draft: string; rows: number } | null {
const styled = styledScreen.split(/\r?\n/)
const lines = styled.map((l) => l.replace(ANSI, '').trimEnd())
if (lines.every((l) => l === '')) return null
if (readClaudeScreen(styledScreen).kind !== 'prompt') return null
const box = inputBox(lines)
if (!box) return null
let draft = ''
for (let i = box[0] + 1; i < box[1]; i++) {
const from = i === box[0] + 1 && lines[i].startsWith('❯') ? 1 : 0
draft += undimmedText(styled[i], from)
}
return { draft: draft.replace(/\s/g, ''), rows: box[1] - box[0] - 1 }
}
/**
* Why a draft in Claude Code's input box cannot be read back EXACTLY (`readClaudeDraftLine`):
* - `multi-line` — it takes more than one row. MEASURED (2.1.319): a line that wraps and a real
* newline (M-Enter) look the same, a second row indented two spaces, and the wrap drops the space
* at the break, so neither the newlines nor the spaces could be put back.
* - `placeholder` — it holds a collapsed paste or image (`[Pasted text #1 +12 lines]`, `[Image #1]`):
* the screen shows the placeholder, not the text behind it.
* - `not-prompt` — the row does not start with the ordinary `❯` prompt (shell mode's `!`, say).
*/
export type ClaudeDraftLineRefusal = 'multi-line' | 'placeholder' | 'not-prompt'
export type ClaudeDraftLine =
| { kind: 'empty' }
| { kind: 'line'; text: string }
| { kind: 'refused'; reason: ClaudeDraftLineRefusal }
const DRAFT_PLACEHOLDER = /\[(?:Pasted text|Image) #\d+/
/**
* The user's draft in Claude Code's input box, read from a STYLED capture, EXACTLY: only when it is
* one row with the ordinary prompt and no collapsed paste, so the text can be handed to the ⌘M chat
* composer as typed (the dim placeholder and any dim inline hint are not part of it; trailing spaces
* are lost, as tmux trims them). null when there is no live input box to read.
*/
export function readClaudeDraftLine(styledScreen: string): ClaudeDraftLine | null {
const composer = readClaudeComposer(styledScreen)
if (composer === 'empty') return { kind: 'empty' }
if (composer !== 'draft') return null
const styled = styledScreen.split(/\r?\n/)
const lines = styled.map((l) => l.replace(ANSI, '').trimEnd())
const box = inputBox(lines)
if (!box) return null
const promptAt = box[0] + 1
for (let i = promptAt + 1; i < box[1]; i++) {
if (lines[i].trim() !== '') return { kind: 'refused', reason: 'multi-line' }
}
if (!lines[promptAt].startsWith('❯')) return { kind: 'refused', reason: 'not-prompt' }
// The prompt is `❯` and one space; everything after it that is not dim is the draft.
const text = undimmedText(styled[promptAt], 1).replace(/^[ \u00a0]/, '').trimEnd()
if (text === '') return { kind: 'empty' }
if (DRAFT_PLACEHOLDER.test(text)) return { kind: 'refused', reason: 'placeholder' }
return { kind: 'line', text }
}
/**
* The next prompt Claude Code suggests after a turn, read from a STYLED capture: the dim text on its
* prompt line while the input box holds no draft. null when there is none to offer.
*
* MEASURED on Claude Code 2.1.318: a few seconds after a turn ends, and only when there is an
* obvious next step, Claude draws a suggestion as plain dim text (`❯ run it in the background`);
* pressing → in its TUI accepts it. Two other dim texts sit in the same place and are NOT
* suggestions: the fresh-session tips, always `Try "…"`, and `Press up to edit queued messages`
* while a turn runs with a message queued. Both are refused here.
*
* Only dim text counts, so a capture that lost its SGR reads as a draft (`readClaudeComposer`) and
* offers nothing.
*/
export function readClaudeSuggestion(styledScreen: string): string | null {
const styled = styledScreen.split(/\r?\n/)
const lines = styled.map((l) => l.replace(ANSI, '').trimEnd())
if (lines.every((l) => l === '')) return null
if (readClaudeScreen(styledScreen).kind !== 'prompt') return null
// `empty`: a `❯` prompt line holding only dim text, and nothing on the lines under it.
if (readClaudeComposer(styledScreen) !== 'empty') return null
const box = inputBox(lines)
if (!box) return null
const suggestion = lines[box[0] + 1].slice(1).trim()
if (suggestion === '' || NOT_SUGGESTIONS.some((re) => re.test(suggestion))) return null
return suggestion
}
/** Dim texts on the prompt line that Claude Code draws but does not suggest (see above). */
const NOT_SUGGESTIONS: readonly RegExp[] = [/^Try "/, /^Press up to edit queued messages$/]