{"slug":"terminal-stream","category":"code","job":"oversee","added":"2026-09-12T06:58Z","title":"Terminal Stream","description":"An auto-scrolling, collapsible panel streaming raw command output line by line.","url":"https://ai-patterns.app/patterns/code/terminal-stream","markdown":"https://ai-patterns.app/patterns/code/terminal-stream.md","json":"https://ai-patterns.app/api/patterns/code/terminal-stream","seenIn":[{"team":"Warp","source":"https://docs.warp.dev/agents/local-agents/agent-context/blocks-as-context"}],"spec":"# Terminal Stream\n\n## Summary\nAn auto-scrolling, collapsible panel that streams a command's raw output line by line, tinted by level (info, warning, error, success) — the closest thing in the catalogue to a real terminal, for when the full, unstructured output of a running process is worth showing.\n\n## When to use\n- An agent or tool is executing a shell command, build, test run, or deploy, and its raw output has real value beyond \"it succeeded\" (debugging a failure, watching a long build).\n- The user should be able to collapse it out of the way once they trust it's just noise, without losing the output entirely.\n\n## When not to use\n- For a single tool call's status with no meaningful line-by-line output — use a Tool Call Chip instead.\n- For output that's actually structured data (a diff, a table, a list of files) — render it as that shape (e.g. Diff Summary) rather than flattening it into log lines.\n- As a permanent, always-expanded fixture once the command is long done — let it collapse to a compact header so it doesn't dominate the surrounding content.\n\n## Anatomy\n- Header bar: a terminal icon, the command itself (monospace), a status indicator (running / done / error), a line count, and a collapse toggle.\n- Log body: monospace lines, each tinted by level — default, info, warning, error, success.\n- A blinking cursor at the tail while still streaming.\n- A \"Jump to latest\" pill that appears only when the user has scrolled away from the bottom during an active stream.\n\n## Behavior\n- New lines append at the bottom and the panel auto-scrolls to keep the latest line in view, as long as the user hasn't manually scrolled up.\n- Scrolling up during an active stream pauses auto-scroll and reveals \"Jump to latest\"; clicking it snaps back to the bottom and resumes auto-scroll.\n- Collapsing hides the log body but keeps the header — including a live line count and status — visible; output keeps accumulating in the background while collapsed.\n- On completion, the header's status swaps to done or error; the log itself is never cleared or replaced, so scrollback stays available.\n\n## Content guidelines\n- Tint lines by their actual level — don't invent color meaning for lines that are all the same kind of output.\n- The header shows the literal command, not a paraphrase or summary of what it does.\n\n## Accessibility\n- The log region is a live region only while actively streaming and expanded (`aria-live=\"polite\"`) — throttle or batch announcements for high-volume output rather than announcing every line.\n- The collapse toggle exposes `aria-expanded`.\n- The log body is a real scrollable, focusable region reachable and operable by keyboard, not just by mouse drag.\n- Status is conveyed by icon and text together, never color alone.\n\n## Related patterns\n- **Tool Call Chip** — Use it instead when only the fact of the call matters, and expand to Terminal Stream when its full output does.\n- **Diff Summary Card** — Use it instead once the command is done and the outcome is file edits rather than log lines.\n- **Console Error Card** — Use it instead when one browser error needs to be surfaced on its own rather than in a stream of output.\n","code":"\"use client\";\n\nimport * as React from \"react\";\nimport { AnimatePresence, motion } from \"motion/react\";\nimport { ArrowDown, Check, ChevronDown, CircleDot, Terminal, X } from \"lucide-react\";\n\nimport { cn } from \"@/lib/utils\";\n\nexport interface LogLine {\n id: string;\n text: string;\n level?: \"default\" | \"info\" | \"warn\" | \"error\" | \"success\";\n}\n\nexport type TerminalStatus = \"running\" | \"done\" | \"error\";\n\nexport interface TerminalStreamProps {\n command: string;\n lines: LogLine[];\n status: TerminalStatus;\n defaultOpen?: boolean;\n className?: string;\n}\n\nconst LEVEL_CLASS: Record, string> = {\n default: \"text-neutral-300\",\n info: \"text-sky-400\",\n warn: \"text-amber-400\",\n error: \"text-red-400\",\n success: \"text-emerald-400\",\n};\n\nexport function TerminalStream({\n command,\n lines,\n status,\n defaultOpen = true,\n className,\n}: TerminalStreamProps) {\n const [open, setOpen] = React.useState(defaultOpen);\n const [pinnedToBottom, setPinnedToBottom] = React.useState(true);\n const bodyRef = React.useRef(null);\n\n React.useEffect(() => {\n if (!open || !pinnedToBottom) return;\n const el = bodyRef.current;\n if (el) el.scrollTop = el.scrollHeight;\n }, [lines, open, pinnedToBottom]);\n\n function handleScroll() {\n const el = bodyRef.current;\n if (!el) return;\n const atBottom = el.scrollHeight - el.scrollTop - el.clientHeight < 24;\n setPinnedToBottom(atBottom);\n }\n\n function jumpToLatest() {\n const el = bodyRef.current;\n if (el) el.scrollTop = el.scrollHeight;\n setPinnedToBottom(true);\n }\n\n return (\n \n setOpen((v) => !v)}\n aria-expanded={open}\n className=\"flex w-full items-center gap-2 px-3.5 py-2.5 text-left text-sm\"\n >\n \n {command}\n \n {lines.length}\n \n \n\n \n {open && (\n \n \n {lines.map((line) => (\n

\n {line.text}\n

\n ))}\n {status === \"running\" && }\n \n\n {!pinnedToBottom && (\n \n Jump to latest\n \n )}\n \n )}\n \n \n );\n}\n\nfunction StatusBadge({ status }: { status: TerminalStatus }) {\n if (status === \"running\") {\n return ;\n }\n if (status === \"error\") {\n return ;\n }\n return ;\n}\n\nfunction BlinkingCursor() {\n return (\n \n );\n}\n","dependencies":["lucide-react","motion"],"localImports":["@/lib/utils"]}