Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
import Foundation
/// Stage one: a rendered frame becomes a typed model of what is on screen.
///
/// The parser is a *reader*, not an interpreter. It is allowed to say "row 11
/// contains a tool-call row for `Update` with the argument `calc.py`" because
/// that is what the characters say. It is not allowed to say "the agent called
/// the Edit tool with `{file_path: ...}`", because the frame does not contain
/// that and inventing it is precisely the failure this module exists to
/// prevent (`FRICTION.md` §93).
///
/// Everything that is a conclusion rather than a reading is marked `.inferred`
/// and travels to the consumer that way. Everything the parser cannot classify
/// comes back as `.rawText` — degrading to plain text is the required
/// behaviour when Claude Code's layout moves, not an error.
public struct ClaudeCodeParser: Sendable {
/// The layout this parser was written against.
public static let layoutProfile = "claude-code/2.x"
public init() {}
public func parse(frame: RenderedFrame) -> ParsedFrame {
let lines = frame.lines
var elements: [TranscriptElement] = []
// A frame that is not on the alternate screen is not the agent UI.
// Claude Code enters the alternate buffer for its TUI; shell
// scrollback, an exited session, or a `claude -p` run is not something
// this layout profile describes, and claiming otherwise would be the
// whole defect. Hand the text back and say so.
guard frame.screen.isAlternateScreen else {
return ParsedFrame(elements: nonEmptyRawText(lines),
cli: frame.cli, cliVersion: frame.cliVersion,
layoutProfile: nil,
frameTime: frame.effectiveTime,
unsupportedSequences: frame.unsupportedSequences,
isAlternateScreen: false)
}
var index = 0
var unclassified: [(Int, String)] = []
func flushUnclassified() {
guard !unclassified.isEmpty else { return }
let body = unclassified.map(\.1)
if body.contains(where: { !$0.trimmed.isEmpty }) {
elements.append(.rawText(RawText(
lines: body,
region: FrameRegion(firstRow: unclassified[0].0,
lastRow: unclassified[unclassified.count - 1].0))))
}
unclassified.removeAll()
}
while index < lines.count {
let line = lines[index]
if let composer = parseComposer(lines: lines, at: index) {
flushUnclassified()
elements.append(.composer(composerElement(composer, frame: frame)))
index = composer.lastRow + 1
continue
}
if let question = parseQuestion(lines: lines, at: index) {
flushUnclassified()
elements.append(.question(question.value))
index = question.nextRow
continue
}
if let mode = parseModeIndicator(line: line, row: index) {
flushUnclassified()
elements.append(.modeIndicator(mode))
index += 1
continue
}
// Order matters: the completion line reuses a spinner glyph
// ("✻ Cogitated for 5s · done 5:58 PM"), so it has to be claimed
// as a turn boundary before the working-indicator rule sees it.
if let boundary = parseTurnBoundary(line: line, row: index) {
flushUnclassified()
elements.append(.turnBoundary(boundary))
index += 1
continue
}
if let running = parseAgentRunning(line: line, row: index) {
flushUnclassified()
elements.append(.agentRunning(running))
index += 1
continue
}
if let banner = parseErrorBanner(line: line, row: index) {
flushUnclassified()
elements.append(.error(banner))
index += 1
continue
}
if let bullet = parseBulletRow(lines: lines, frame: frame, at: index) {
flushUnclassified()
elements.append(contentsOf: bullet.elements)
index = bullet.nextRow
continue
}
if let summary = parseActivitySummary(lines: lines, at: index) {
flushUnclassified()
elements.append(.toolCall(summary.value))
index = summary.nextRow
continue
}
if let user = parseUserMessage(lines: lines, at: index) {
flushUnclassified()
elements.append(.userMessage(user.value))
index = user.nextRow
continue
}
unclassified.append((index, line))
index += 1
}
flushUnclassified()
return ParsedFrame(elements: elements,
cli: frame.cli, cliVersion: frame.cliVersion,
layoutProfile: elements.contains(where: { $0.provenance != .unrecognised })
? Self.layoutProfile : nil,
frameTime: frame.effectiveTime,
unsupportedSequences: frame.unsupportedSequences,
isAlternateScreen: true)
}
// MARK: - Raw fallback
private func nonEmptyRawText(_ lines: [String]) -> [TranscriptElement] {
var out: [TranscriptElement] = []
var run: [(Int, String)] = []
func flush() {
if run.contains(where: { !$0.1.trimmed.isEmpty }) {
out.append(.rawText(RawText(lines: run.map(\.1),
region: FrameRegion(firstRow: run[0].0,
lastRow: run[run.count - 1].0))))
}
run.removeAll()
}
for (row, line) in lines.enumerated() {
if line.trimmed.isEmpty && run.isEmpty { continue }
run.append((row, line))
}
flush()
return out
}
// MARK: - The bullet rows
/// Claude Code draws every transcript entry as a `⏺` bullet in column 1
/// followed by either prose (an agent message) or `Name(arg)` (a tool
/// call), with `⎿` continuation rows underneath for results.
private struct BulletResult {
let elements: [TranscriptElement]
let nextRow: Int
}
private func parseBulletRow(lines: [String], frame: RenderedFrame,
at row: Int) -> BulletResult? {
let line = lines[row]
let trimmedLeading = line.drop(while: { $0 == " " })
guard let first = trimmedLeading.first, Self.bulletGlyphs.contains(first) else {
return nil
}
let head = String(trimmedLeading.dropFirst()).trimmed
guard !head.isEmpty else { return nil }
// Gather the continuation block: the `⎿` result rows and any indented
// rows that belong with them.
var lastRow = row
var resultLines: [String] = []
var scan = row + 1
var sawContinuationMarker = false
while scan < lines.count {
let candidate = lines[scan]
let stripped = candidate.trimmed
if stripped.isEmpty { break }
let firstNonSpace = candidate.drop(while: { $0 == " " }).first
if let glyph = firstNonSpace, Self.bulletGlyphs.contains(glyph) { break }
if let glyph = firstNonSpace, Self.continuationGlyphs.contains(glyph) {
sawContinuationMarker = true
resultLines.append(String(candidate.drop(while: { $0 == " " }).dropFirst()).trimmed)
lastRow = scan
scan += 1
continue
}
// An indented row only belongs to this entry once a `⎿` has
// introduced the block. Otherwise it is a wrapped prose line and
// is handled as part of the message body below.
if sawContinuationMarker && candidate.hasPrefix(" ") {
resultLines.append(stripped)
lastRow = scan
scan += 1
continue
}
break
}
let region = FrameRegion(firstRow: row, lastRow: lastRow)
// `Agent "List functions in calc.py" finished · 4s` — the CLI's own
// completion row for a backgrounded subagent. Both the task and the
// outcome are literally drawn, so this is `.observed` end to end.
if let finished = Self.agentFinishedRow(head) {
return BulletResult(elements: [.subagent(Subagent(
kind: "Agent", task: finished.task,
status: finished.failed ? .failed : .succeeded,
statusProvenance: .observed,
detailLines: resultLines,
region: region))], nextRow: lastRow + 1)
}
if let call = Self.toolCallPattern(head) {
if Self.subagentTools.contains(call.name) {
let joined = resultLines.joined(separator: " ").lowercased()
let subagentStatus: ToolCallStatus
let subagentStatusProvenance: Provenance
if joined.contains("backgrounded") || joined.contains("running") {
// "Backgrounded agent (↓ to manage)" says it was launched,
// not that it finished. Reading that as a result would
// report a running subagent as done.
subagentStatus = .running
subagentStatusProvenance = .inferred
} else if resultLines.isEmpty {
subagentStatus = .running
subagentStatusProvenance = .inferred
} else {
subagentStatus = status(for: resultLines)
subagentStatusProvenance = .observed
}
return BulletResult(elements: [.subagent(Subagent(
kind: call.name,
task: call.argument,
status: subagentStatus,
statusProvenance: subagentStatusProvenance,
detailLines: resultLines,
region: region))], nextRow: lastRow + 1)
}
var produced: [TranscriptElement] = []
let collapsed = resultLines.contains { Self.collapsedHints.contains(where: $0.contains) }
produced.append(.toolCall(ToolCall(
name: call.name,
argumentSummary: call.argument,
status: status(for: resultLines),
// "running" is never on the screen. It is our reading of a
// call row that has no result under it yet, and it is labelled
// as such so a renderer cannot present it as the agent's word.
statusProvenance: resultLines.isEmpty ? .inferred : .observed,
resultLines: resultLines,
isCollapsed: collapsed,
region: region)))
if let diff = parseDiff(frame: frame, path: call.argument,
firstRow: row + 1, lastRow: lastRow) {
produced.append(.diff(diff))
}
return BulletResult(elements: produced, nextRow: lastRow + 1)
}
// A bullet whose continuation block opens with `$ <command>` is a
// shell call the CLI has titled with the agent's own description
// rather than a tool name. Both parts are kept: the description as the
// message it is, and the command as a call whose *name* is our
// conclusion (the word "Bash" is nowhere on the screen) and so is
// labelled `.inferred`.
if let first = resultLines.first, first.hasPrefix("$ ") {
let command = String(first.dropFirst(2))
let rest = Array(resultLines.dropFirst())
return BulletResult(elements: [
.agentMessage(AgentMessage(markdown: head, text: head,
region: FrameRegion(row: row))),
.toolCall(ToolCall(name: "Bash", argumentSummary: command,
status: rest.isEmpty ? .running : status(for: rest),
statusProvenance: .inferred,
resultLines: rest,
isCollapsed: rest.contains { line in
Self.collapsedHints.contains(where: line.contains)
},
region: FrameRegion(firstRow: row + 1, lastRow: lastRow),
provenance: .inferred)),
], nextRow: lastRow + 1)
}
// Not `Name(arg)`: prose. Continue through wrapped lines, which the
// CLI indents to the bullet's text column.
// A message is not one run of lines. Claude Code separates paragraphs
// and list blocks inside a single message with a blank row, so a
// parser that stops at the first blank splits one message into a
// paragraph and a pile of `rawText` — which is exactly the "markdown
// structure preserved" requirement failing quietly. A blank row is
// therefore kept only when the row after it is still part of the
// message body.
var body = [head]
var prose = row + 1
var lastContent = row
var pendingBlanks = 0
while prose < lines.count {
let candidate = lines[prose]
if candidate.trimmed.isEmpty {
pendingBlanks += 1
if pendingBlanks > 1 { break }
prose += 1
continue
}
let firstNonSpace = candidate.drop(while: { $0 == " " }).first
if let glyph = firstNonSpace,
Self.bulletGlyphs.contains(glyph) || Self.continuationGlyphs.contains(glyph)
|| Self.promptGlyphs.contains(glyph) { break }
guard candidate.hasPrefix(" "), !Self.isHorizontalRule(candidate) else { break }
if parseModeIndicator(line: candidate, row: prose) != nil { break }
if parseTurnBoundary(line: candidate, row: prose) != nil { break }
if parseAgentRunning(line: candidate, row: prose) != nil { break }
for _ in 0..<pendingBlanks { body.append("") }
pendingBlanks = 0
body.append(candidate.trimmed)
lastContent = prose
prose += 1
}
let text = body.joined(separator: "\n")
return BulletResult(elements: [.agentMessage(AgentMessage(
markdown: Markdown.fromScreenLines(body),
text: text,
region: FrameRegion(firstRow: row, lastRow: lastContent)))],
nextRow: lastContent + 1)
}
private func status(for resultLines: [String]) -> ToolCallStatus {
guard !resultLines.isEmpty else { return .running }
let joined = resultLines.joined(separator: " ").lowercased()
if Self.errorMarkers.contains(where: joined.contains) { return .failed }
if Self.successMarkers.contains(where: joined.contains) { return .succeeded }
return .completed
}
// MARK: - Diffs
/// A Claude Code edit draws numbered source lines whose *background*
/// colour is the only thing distinguishing an addition from a removal.
/// That is why the emulator keeps attributes: read as text alone, a diff
/// is indistinguishable from a file listing.
private func parseDiff(frame: RenderedFrame, path: String?,
firstRow: Int, lastRow: Int) -> Diff? {
guard firstRow <= lastRow else { return nil }
var hunk: [Diff.Line] = []
var added = 0, removed = 0
var anySignDrawn = false
for row in firstRow...min(lastRow, frame.screen.rows - 1) {
let text = frame.screen.line(row)
guard let numbered = Self.numberedSourceLine(text) else { continue }
let kind: Diff.Line.Kind
if let sign = numbered.sign {
// 2.1.x draws a literal `+`/`-` between the line number and
// the source. When it is there, "added" is something the agent
// wrote, not something we concluded.
anySignDrawn = true
kind = sign == "+" ? .added : .removed
} else {
switch dominantBackground(frame: frame, row: row) {
case .some(.indexed(let index)) where Self.addedBackgrounds.contains(index):
kind = .added
case .some(.indexed(let index)) where Self.removedBackgrounds.contains(index):
kind = .removed
default:
kind = .context
}
}
if kind == .added { added += 1 }
if kind == .removed { removed += 1 }
hunk.append(Diff.Line(kind: kind, number: numbered.number, text: numbered.text))
}
guard !hunk.isEmpty, added + removed > 0 else { return nil }
return Diff(path: path, hunkLines: hunk, addedCount: added, removedCount: removed,
region: FrameRegion(firstRow: firstRow, lastRow: lastRow),
// If the `+`/`-` markers were drawn, the classification is
// a reading. If it rests on background colour alone, it is
// our conclusion and is labelled as one — a consumer can
// then decide whether a colour-derived diff is good enough
// to render as a diff.
provenance: anySignDrawn ? .observed : .inferred)
}
private func dominantBackground(frame: RenderedFrame, row: Int) -> TerminalColor? {
var counts: [TerminalColor: Int] = [:]
for column in 0..<frame.screen.columns {
if let background = frame.screen[row, column].attributes.background {
counts[background, default: 0] += 1
}
}
// Require a real run, not a stray cell.
return counts.filter { $0.value >= 4 }.max { $0.value < $1.value }?.key
}
// MARK: - Composer
private struct ComposerBox { let firstRow: Int; let lastRow: Int; let body: [String] }
/// 2.1.x draws the composer as two full-width horizontal rules with the
/// prompt rows between them. Earlier builds drew a rounded box
/// (`╭─…╮ │ … │ ╰─…╯`), so both are accepted: recognising one layout and
/// silently mis-reading the other is the failure mode this module is for.
private func parseComposer(lines: [String], at row: Int) -> ComposerBox? {
if let boxed = parseBoxedComposer(lines: lines, at: row) { return boxed }
return parseRuledComposer(lines: lines, at: row)
}
private func parseBoxedComposer(lines: [String], at row: Int) -> ComposerBox? {
let line = lines[row]
guard line.hasPrefix("╭"), line.contains("─"), line.hasSuffix("╮") else { return nil }
var scan = row + 1
var body: [String] = []
while scan < lines.count {
let candidate = lines[scan]
if candidate.hasPrefix("╰") { return ComposerBox(firstRow: row, lastRow: scan, body: body) }
guard candidate.hasPrefix("│") else { return nil }
var inner = String(candidate.dropFirst())
if inner.hasSuffix("│") { inner = String(inner.dropLast()) }
body.append(inner)
scan += 1
if scan - row > 24 { return nil }
}
return nil
}
private func parseRuledComposer(lines: [String], at row: Int) -> ComposerBox? {
guard Self.isHorizontalRule(lines[row]) else { return nil }
var scan = row + 1
var body: [String] = []
while scan < lines.count, scan - row <= 12 {
let candidate = lines[scan]
if Self.isHorizontalRule(candidate) {
// A pair of rules with nothing prompt-shaped between them is
// a divider, not the composer.
guard body.contains(where: { $0.drop(while: { $0 == " " }).first.map(Self.promptGlyphs.contains) ?? false })
else { return nil }
return ComposerBox(firstRow: row, lastRow: scan, body: body)
}
body.append(candidate)
scan += 1
}
return nil
}
private func composerElement(_ box: ComposerBox, frame: RenderedFrame) -> Composer {
var content: [String] = []
var promptColumn = 0
for (offset, raw) in box.body.enumerated() {
var text = raw.trimmed
if let first = text.first, Self.promptGlyphs.contains(first) {
if offset == 0 {
promptColumn = (raw.count - raw.drop(while: { $0 == " " }).count) + 2
}
text = String(text.dropFirst()).trimmed
}
content.append(text)
}
while let last = content.last, last.isEmpty { content.removeLast() }
let joined = content.joined(separator: "\n")
// A placeholder is dim; typed text is not. Reading it off the cells is
// the difference between "the user typed nothing" and "the user typed
// the placeholder", which a text-only parser cannot tell apart.
var placeholder: String?
if !joined.isEmpty, box.firstRow + 1 < frame.screen.rows {
let attributes = frame.screen.attributes(row: box.firstRow + 1)
let bodyAttributes = attributes.dropFirst(promptColumn).prefix(joined.count)
if !bodyAttributes.isEmpty && bodyAttributes.allSatisfy({ $0.dim }) {
placeholder = joined
}
}
let cursorInside = frame.screen.cursorRow > box.firstRow
&& frame.screen.cursorRow < box.lastRow
return Composer(content: placeholder == nil ? joined : "",
placeholder: placeholder,
cursorIsInside: cursorInside,
region: FrameRegion(firstRow: box.firstRow, lastRow: box.lastRow))
}
// MARK: - Mode indicator
private func parseModeIndicator(line: String, row: Int) -> ModeIndicator? {
let text = line.trimmed
guard !text.isEmpty else { return nil }
let lowered = text.lowercased()
// The footer is recognisable by its cycle hint, which is the one part
// that has not moved across releases.
guard lowered.contains("shift+tab to cycle") || lowered.contains("shift-tab to cycle")
|| lowered.hasPrefix("⏵⏵") || lowered.hasPrefix("⏸") else { return nil }
let hint = Self.captureGroup(in: text, pattern: "\\((shift\\+tab to cycle[^)]*)\\)")
let mode: PermissionMode
if lowered.contains("accept edits") { mode = .acceptEdits }
else if lowered.contains("plan mode") { mode = .plan }
else if lowered.contains("bypass") || lowered.contains("dangerously") { mode = .bypassPermissions }
else if lowered.contains("auto mode") { mode = .auto }
else if lowered.contains("manual mode") { mode = .manual }
else { mode = .unrecognised }
return ModeIndicator(mode: mode, rawText: text, hint: hint,
region: FrameRegion(row: row),
// The words are on screen; mapping them onto our
// enum is ours. When the mapping fails we say
// `.unrecognised` and hand back `rawText`.
provenance: mode == .unrecognised ? .unrecognised : .observed)
}
// MARK: - Working indicator
private func parseAgentRunning(line: String, row: Int) -> AgentRunning? {
let text = line.trimmed
guard let first = text.first, Self.spinnerGlyphs.contains(first) else { return nil }
let rest = String(text.dropFirst()).trimmed
guard !rest.isEmpty else { return nil }
// "Channeling… (3s · ↓ 59 tokens)" — the verb is the leading word with
// its ellipsis removed. Claude Code rotates these words constantly;
// they are quoted back, never mapped onto a state vocabulary we made
// up, because "Channeling" does not mean anything the SDK can define.
let verb = rest.split(separator: " ").first
.map { String($0).trimmingCharacters(in: CharacterSet(charactersIn: "…·.")) }
.flatMap { $0.isEmpty ? nil : $0 }
let elapsed = Self.captureGroup(in: rest, pattern: "for (\\d+)s").flatMap { Int($0) }
?? Self.captureGroup(in: rest, pattern: "\\((\\d+)s").flatMap { Int($0) }
let tokensText = Self.captureGroup(in: rest, pattern: "([\\d,]+) tokens")
let tokens = tokensText.flatMap { Int($0.replacingOccurrences(of: ",", with: "")) }
let hint = Self.captureGroup(in: rest, pattern: "(esc to interrupt[^)]*)")
return AgentRunning(spinner: String(first), verb: verb,
elapsedSeconds: elapsed, tokens: tokens, hint: hint,
rawLine: text, region: FrameRegion(row: row))
}
// MARK: - Turn boundaries
private func parseTurnBoundary(line: String, row: Int) -> TurnBoundary? {
let text = line.trimmed
guard !text.isEmpty else { return nil }
let lowered = text.lowercased()
if lowered.contains("interrupted by user") || lowered.contains("request interrupted") {
return TurnBoundary(kind: .interrupted, text: text, region: FrameRegion(row: row))
}
// "✻ Baked for 4s · done 5:55 PM" — the CLI's own completion line.
if let first = text.first, Self.spinnerGlyphs.contains(first),
lowered.contains("· done") {
return TurnBoundary(kind: .completed, text: text, region: FrameRegion(row: row))
}
return nil
}
// MARK: - Error banners
/// A standalone error row: the CLI marks these with a cross or a bare
/// `Error:` prefix, outside any tool row. Matching on the marker keeps
/// this from claiming every sentence that contains the word "error" —
/// including the agent's own prose *about* an error, which is a message,
/// not a banner.
private func parseErrorBanner(line: String, row: Int) -> ErrorBanner? {
let text = line.trimmed
guard !text.isEmpty else { return nil }
if let first = text.first, Self.errorGlyphs.contains(first) {
return ErrorBanner(text: String(text.dropFirst()).trimmed,
region: FrameRegion(row: row))
}
let lowered = text.lowercased()
guard lowered.hasPrefix("error:") || lowered.hasPrefix("api error")
|| lowered.hasPrefix("fatal:") else { return nil }
return ErrorBanner(text: text, region: FrameRegion(row: row))
}
// MARK: - Questions
private struct QuestionResult { let value: Question; let nextRow: Int }
private func parseQuestion(lines: [String], at row: Int) -> QuestionResult? {
// The rule is structural, not lexical: a line that asks something,
// followed by numbered options. Matching on the wording ("Do you want
// to…") fails the moment the CLI rephrases, and the rephrasing is
// exactly when a mis-parse would be least visible.
let text = lines[row].trimmed
guard text.hasSuffix("?"), text.count > 3 else { return nil }
var options: [Question.Option] = []
var selected: Int?
var scan = row + 1
var last = row
while scan < lines.count, scan - row < 12 {
let candidate = lines[scan].trimmed
if candidate.isEmpty { scan += 1; continue }
guard let option = Self.optionPattern(candidate) else {
// Only blank rows may separate the prompt from its first
// option. Skipping arbitrary prose would let any question mark
// anywhere on screen adopt an unrelated numbered list.
if options.isEmpty { return nil }
break
}
if option.selected { selected = options.count }
options.append(Question.Option(key: option.key, label: option.label))
last = scan
scan += 1
}
guard !options.isEmpty else { return nil }
return QuestionResult(value: Question(prompt: text, options: options,
selectedIndex: selected,
region: FrameRegion(firstRow: row, lastRow: last)),
nextRow: last + 1)
}
// MARK: - Bullet-less tool activity
private struct SummaryResult { let value: ToolCall; let nextRow: Int }
/// While a turn is in flight, and after it collapses, Claude Code draws
/// tool activity *without* a bullet and without the `Name(arg)` shape:
/// ` Reading calc.py` with ` ⎿ calc.py` under it, or ` Read 1 file`
/// once the call has folded away.
///
/// These are emitted as tool calls because that is plainly what they are,
/// but the whole element is `.inferred`: the CLI never wrote a tool name
/// here. "Reading" is a participle in a status line, and treating it as
/// `ToolCall.name == "Reading"` is our reading of the sentence, not the
/// agent's declaration of a call. A consumer that wants only calls the
/// agent actually named can filter on `provenance == .observed`.
private func parseActivitySummary(lines: [String], at row: Int) -> SummaryResult? {
let line = lines[row]
guard line.hasPrefix(" "), !line.hasPrefix(" ") else { return nil }
let text = line.trimmed
guard let first = text.first, first.isUppercase else { return nil }
let words = text.split(separator: " ")
guard let head = words.first.map(String.init),
Self.activityVerbs.contains(head) else { return nil }
var resultLines: [String] = []
var last = row
var scan = row + 1
while scan < lines.count {
let candidate = lines[scan]
let firstNonSpace = candidate.drop(while: { $0 == " " }).first
guard let glyph = firstNonSpace, Self.continuationGlyphs.contains(glyph) else { break }
resultLines.append(String(candidate.drop(while: { $0 == " " }).dropFirst()).trimmed)
last = scan
scan += 1
}
let argument = words.dropFirst().joined(separator: " ")
return SummaryResult(value: ToolCall(
name: head,
argumentSummary: argument.isEmpty ? nil : argument,
// An activity row with nothing under it is *not* evidence that the
// call is still running: it is just as likely to be a finished
// call the CLI has folded away. `.unknown` is the only status this
// shape supports.
status: resultLines.isEmpty ? .unknown : status(for: resultLines),
statusProvenance: .inferred,
resultLines: resultLines,
isCollapsed: resultLines.contains { Self.collapsedHints.contains(where: $0.contains) },
region: FrameRegion(firstRow: row, lastRow: last),
provenance: .inferred), nextRow: last + 1)
}
// MARK: - User messages
private struct UserResult { let value: UserMessage; let nextRow: Int }
/// The transcript echoes what the user sent as `> text`, left-aligned and
/// outside any box. The composer is a box and is matched first, so a `>`
/// row reaching here is a sent message.
private func parseUserMessage(lines: [String], at row: Int) -> UserResult? {
let line = lines[row]
let stripped = line.drop(while: { $0 == " " })
guard let marker = stripped.first, Self.promptGlyphs.contains(marker),
stripped.dropFirst().hasPrefix(" ") else { return nil }
var body = [String(stripped.dropFirst(2)).trimmed]
var scan = row + 1
while scan < lines.count {
let candidate = lines[scan]
guard candidate.hasPrefix(" "), !candidate.trimmed.isEmpty else { break }
let firstNonSpace = candidate.drop(while: { $0 == " " }).first
if let glyph = firstNonSpace, Self.promptGlyphs.contains(glyph) { break }
if let glyph = firstNonSpace,
Self.bulletGlyphs.contains(glyph) || Self.continuationGlyphs.contains(glyph)
|| Self.spinnerGlyphs.contains(glyph) { break }
body.append(candidate.trimmed)
scan += 1
}
return UserResult(value: UserMessage(text: body.joined(separator: "\n"),
region: FrameRegion(firstRow: row, lastRow: scan - 1)),
nextRow: scan)
}
}
// MARK: - Vocabulary
extension ClaudeCodeParser {
/// The glyphs Claude Code uses to open a transcript entry.
static let bulletGlyphs: Set<Character> = ["⏺", "●"]
/// The glyph that opens a result/continuation row.
static let continuationGlyphs: Set<Character> = ["⎿", "└", "╰"]
/// The spinner frames. Claude Code rotates through these on the working
/// row and reuses the last one on the completion line.
static let spinnerGlyphs: Set<Character> = ["✻", "✽", "✶", "✳", "✢", "·", "∗", "*"]
/// Tools whose row means "a subagent is doing this".
static let subagentTools: Set<String> = ["Task", "Agent", "Explore", "Plan",
"general-purpose", "Subagent"]
/// Glyphs that open an error banner.
static let errorGlyphs: Set<Character> = ["✗", "✘", "×", "⚠", "🛑"]
/// The leading words of a bullet-less activity row. Deliberately a closed
/// list: an open rule ("any capitalised first word") turns every sentence
/// into a tool call.
static let activityVerbs: Set<String> = [
"Read", "Reading", "Wrote", "Writing", "Ran", "Running", "Listed",
"Listing", "Searched", "Searching", "Fetched", "Fetching", "Updated",
"Updating", "Created", "Creating", "Edited", "Editing", "Found",
"Deleted", "Deleting", "Globbed", "Grepped",
]
static let errorMarkers = ["error", "failed", "no such file", "denied",
"not found", "cannot ", "exception"]
static let successMarkers = ["added ", "updated ", "read ", "wrote ", "applied ",
"found ", "listed ", "removed ", "created "]
static let collapsedHints = ["ctrl+o to expand", "ctrl-o to expand", "… +", "... +",
"more lines", "expand"]
/// 256-colour background indices Claude Code uses for diff shading. Two
/// families because the palette differs between its light and dark themes.
static let addedBackgrounds: Set<UInt8> = [22, 28, 29, 35, 65, 151, 194, 2]
static let removedBackgrounds: Set<UInt8> = [52, 88, 89, 95, 124, 131, 224, 1]
static func toolCallPattern(_ text: String) -> (name: String, argument: String?)? {
// `Name(argument)` where Name is a bare identifier. Anything else is
// prose that happens to contain a bracket.
guard let open = text.firstIndex(of: "("), text.hasSuffix(")") else {
// A bare `Name` with no argument is also a tool row the CLI draws
// (e.g. `TodoWrite`), but only when the whole line is one word in
// PascalCase — otherwise every one-word sentence becomes a call.
let trimmed = text.trimmed
guard !trimmed.contains(" "), trimmed.count >= 3,
let first = trimmed.first, first.isUppercase,
trimmed.allSatisfy({ $0.isLetter }) else { return nil }
return (trimmed, nil)
}
let name = String(text[text.startIndex..<open])
guard !name.isEmpty, name.allSatisfy({ $0.isLetter || $0 == "_" }),
let first = name.first, first.isUppercase else { return nil }
let argumentStart = text.index(after: open)
let argument = String(text[argumentStart..<text.index(before: text.endIndex)])
return (name, argument.isEmpty ? nil : argument)
}
static func numberedSourceLine(_ text: String) -> (number: Int?, sign: Character?, text: String)? {
// ` 5 def subtract(a, b):` (context)
// ` 9 +def multiply(a, b):` (added)
// A right-aligned line number, then an optional `+`/`-`, then source.
let stripped = text.drop(while: { $0 == " " || $0 == "\u{a0}" })
let digits = stripped.prefix(while: { $0.isNumber })
guard !digits.isEmpty, let number = Int(digits) else { return nil }
var rest = stripped.dropFirst(digits.count)
guard rest.hasPrefix(" ") else { return nil }
rest = rest.dropFirst()
if let first = rest.first, first == "+" || first == "-" {
return (number, first, String(rest.dropFirst()))
}
// An unchanged line still reserves the sign column, so drop the blank
// that stands where a `+` would be. Leaving it in shifts every context
// line one space right relative to the lines around it.
if rest.hasPrefix(" ") { rest = rest.dropFirst() }
return (number, nil, String(rest))
}
static func agentFinishedRow(_ text: String) -> (task: String, failed: Bool)? {
guard text.hasPrefix("Agent \""), let closing = text.dropFirst(7).firstIndex(of: "\"")
else { return nil }
let task = String(text[text.index(text.startIndex, offsetBy: 7)..<closing])
let tail = String(text[text.index(after: closing)...]).trimmed.lowercased()
guard tail.hasPrefix("finished") || tail.hasPrefix("failed")
|| tail.hasPrefix("stopped") || tail.hasPrefix("errored") else { return nil }
return (task, tail.hasPrefix("failed") || tail.hasPrefix("errored"))
}
static func isHorizontalRule(_ text: String) -> Bool {
let trimmed = text.trimmed
return trimmed.count >= 20 && trimmed.allSatisfy { $0 == "─" || $0 == "━" || $0 == "—" }
}
/// The glyphs that open a prompt row: the composer's own marker and the
/// echo of a sent message.
static let promptGlyphs: Set<Character> = ["❯", ">", "›"]
static func optionPattern(_ text: String) -> (key: String?, label: String, selected: Bool)? {
// `❯ 1. Yes` / ` 2. No, and tell Claude what to do differently`
var working = text
var selected = false
for marker in ["❯", ">", "▸", "→"] where working.hasPrefix(marker) {
working = String(working.dropFirst(marker.count)).trimmed
selected = true
break
}
let digits = working.prefix(while: { $0.isNumber })
guard !digits.isEmpty else { return nil }
let rest = working.dropFirst(digits.count)
guard rest.hasPrefix(".") || rest.hasPrefix(")") else { return nil }
let label = String(rest.dropFirst()).trimmed
guard !label.isEmpty else { return nil }
return (String(digits), label, selected)
}
static func captureGroup(in text: String, pattern: String) -> String? {
guard let regex = try? NSRegularExpression(pattern: pattern, options: [.caseInsensitive]),
let match = regex.firstMatch(in: text, range: NSRange(text.startIndex..., in: text)),
match.numberOfRanges > 1,
let range = Range(match.range(at: 1), in: text)
else { return nil }
return String(text[range])
}
}
// MARK: - Markdown
enum Markdown {
/// Reconstruct Markdown source from lines the CLI has already rendered.
///
/// This is genuinely lossy and the type system should not pretend
/// otherwise: bold that was drawn with SGR is gone by the time the text is
/// read, and a wrapped paragraph cannot be unwrapped with certainty. What
/// survives is block structure — bullets, numbered items, indented code —
/// which is the part a renderer needs and the part the CLI draws with
/// characters rather than colour.
static func fromScreenLines(_ lines: [String]) -> String {
var out: [String] = []
for line in lines {
var text = line
if text.hasPrefix("• ") || text.hasPrefix("◦ ") || text.hasPrefix("- ") {
text = "- " + text.dropFirst(2)
}
out.append(text)
}
return out.joined(separator: "\n")
}
}
extension StringProtocol {
var trimmed: String { trimmingCharacters(in: .whitespaces) }
}