dwgx/SmartCLI / skills/drive-tui
drive-tui
VerifiedDrive interactive terminal (TUI) programs — CLIs, REPLs, installers, menu apps, agent CLIs, and editors like vim — through a PTY, reading semantic screen snapshots. A pattern library classifies a screen (REPL, menu, pager, fzf search, confirm dialog, form, spinner, wizard) and drives it with a ready recipe. Use when a program expects a live terminal (arrow-key menus, prompts, spinners, password fields, curses UIs), or when a piped command hangs or prints nothing.
_vendor/smartcli_core/snapshot.py
View on GitHub"""Semantic, token-cheap snapshot of a terminal screen for an LLM agent.
A raw screen dump loses the single most actionable fact in a TUI: *which row is
selected*. Reverse-video and themed selection bars are invisible in plain text.
:func:`build_snapshot` scans the per-cell attributes, reduces them to a few
meaning-bearing fields (selected row, menu spans, errors, status bar), and throws
the color grid away.
The :class:`Snapshot` dataclass carries the reduced view and renders two
representations:
* :meth:`Snapshot.to_text` -- a compact view for feeding an LLM: the visible
screen (blank runs collapsed) plus a one-line header describing cursor,
selection and status bar.
* :meth:`Snapshot.to_json` -- the full structured form for programmatic use.
"""
from __future__ import annotations
import json
import re
from dataclasses import dataclass, field
from .screen_model import CellAttrs, ScreenModel
_ERROR_RE = re.compile(r"\b(error|failed|traceback|exception)\b", re.I)
_RED_FGS = {"red", "brightred"}
LineEntry = str | tuple[int, str, bool]
@dataclass
class Span:
"""A contiguous run of highlighted columns on one row (``col_end`` exclusive)."""
row: int
col_start: int
col_end: int
text: str
@dataclass
class Snapshot:
"""Reduced semantic view of a terminal screen.
Attributes:
size: ``(rows, cols)``.
lines: rendered non-blank lines; collapsed blank runs are the literal
marker ``"..."``. Kept as ``(row, text, sel)`` tuples so positional
reasoning survives collapsing.
cursor: ``(row, col)``, 0-based.
cursor_hidden: whether the terminal cursor is hidden.
selected_line: best-guess active row index, or ``None``.
status_bar: bottom hint/status line text, or ``None``.
title: OSC window title, or ``None``.
menu_items: every highlighted span in reading order.
errors: lines flagged as errors, as ``(row, text, reason)``.
screen_reverse: DECSCNM (screen-wide reverse) active.
alt_screen: a full-screen program owns the screen (vim/less/htop).
"""
size: tuple[int, int]
lines: list[LineEntry]
cursor: tuple[int, int]
cursor_hidden: bool = False
selected_line: int | None = None
selected: Span | None = None
selected_reason: str | None = None
status_bar: str | None = None
status_bar_row: int | None = None
title: str | None = None
menu_items: list[Span] = field(default_factory=list)
errors: list[tuple[int, str, str]] = field(default_factory=list)
screen_reverse: bool = False
alt_screen: bool = False
# -- rendering ---------------------------------------------------------
def to_text(self) -> str:
"""Compact LLM-facing view: header line + visible screen.
The header summarises cursor, selection, status bar and any errors so the
agent gets the semantics without a per-cell color grid.
"""
rows, cols = self.size
header_bits = [f"cursor=r{self.cursor[0]}c{self.cursor[1]}"]
if self.cursor_hidden:
header_bits.append("cursor:hidden")
if self.selected is not None:
sel = self.selected
header_bits.append(
f"selected=r{sel.row}[{sel.col_start}:{sel.col_end}]"
f'"{sel.text}"({self.selected_reason})'
)
elif self.selected_line is not None:
header_bits.append(f"selected=r{self.selected_line}")
if self.status_bar:
header_bits.append(f'status="{self.status_bar}"')
if self.title:
header_bits.append(f'title="{self.title}"')
if self.errors:
header_bits.append(f"errors={len(self.errors)}")
if self.alt_screen:
# Leads the flags: it changes what an action MEANS, so an agent
# reading only the start of the header still sees it.
header_bits.insert(1, "alt_screen")
if self.screen_reverse:
header_bits.append("screen_reverse")
header = f"[screen {rows}x{cols}] " + " ".join(header_bits)
body_lines = []
for entry in self.lines:
if isinstance(entry, str):
body_lines.append(entry)
continue
row, text, line_selected = entry
marker = "*" if line_selected else " "
body_lines.append(f"{row:>3}{marker}| {text}")
return header + "\n" + "\n".join(body_lines)
def to_json(self, indent: int | None = None) -> str:
"""Full structured JSON. Empty/None fields are omitted to save tokens."""
rows, cols = self.size
obj: dict = {
"size": {"rows": rows, "cols": cols},
"cursor": {
"row": self.cursor[0],
"col": self.cursor[1],
"hidden": self.cursor_hidden,
},
"lines": [self._line_to_json(entry) for entry in self.lines],
}
if self.title:
obj["title"] = self.title
if self.selected is not None:
obj["selected"] = {
"row": self.selected.row,
"col_start": self.selected.col_start,
"col_end": self.selected.col_end,
"text": self.selected.text,
"reason": self.selected_reason,
}
regions: dict = {}
if self.status_bar is not None:
regions["status_bar"] = {
"row": self.status_bar_row,
"text": self.status_bar,
}
if self.menu_items:
regions["menu_items"] = [
{
"row": s.row,
"col_start": s.col_start,
"col_end": s.col_end,
"text": s.text,
}
for s in self.menu_items
]
if regions:
obj["regions"] = regions
hints: dict = {
"has_hidden_cursor": self.cursor_hidden,
"screen_reverse": self.screen_reverse,
"alt_screen": self.alt_screen,
}
if self.errors:
hints["errors"] = [
{"row": r, "text": t, "reason": reason}
for (r, t, reason) in self.errors
]
obj["hints"] = hints
return json.dumps(obj, indent=indent, ensure_ascii=False)
@staticmethod
def _line_to_json(entry: LineEntry) -> object:
if isinstance(entry, str):
return entry
row, text, selected = entry
return {"row": row, "text": text, **({"sel": True} if selected else {})}
def _contiguous_spans(cols: list[int]) -> list[tuple[int, int]]:
"""``[0,1,2,5,6]`` -> ``[(0,3),(5,7)]`` (end exclusive)."""
spans: list[tuple[int, int]] = []
for x in sorted(cols):
if spans and x == spans[-1][1]:
spans[-1] = (spans[-1][0], x + 1)
else:
spans.append((x, x + 1))
return spans
def build_snapshot(model: ScreenModel) -> Snapshot:
"""Build a :class:`Snapshot` from a :class:`ScreenModel`.
The reverse-video predicate is measured relative to the screen's baseline
(``default_char.reverse``) so a full-screen-reverse app (DECSCNM) does not
report every line as selected.
"""
screen = model.screen
rows, cols = screen.lines, screen.columns
display = model.display
base_reverse = model.base_reverse
# ---- per-cell attribute scan, reduced to per-line facts ----
line_hi_spans: list[list[tuple[int, int]]] = []
line_red: list[bool] = []
line_cells: list[list[CellAttrs]] = []
for y in range(rows):
cells = model.row_cells(y)
line_cells.append(cells)
hi_cols: list[int] = []
red = False
for x, ch in enumerate(cells):
is_blank = ch.data == " "
# Selection/highlight signal: reverse-video, a distinct background,
# or bold. Foreground colour alone is deliberately NOT treated as a
# highlight — syntax-coloured REPL/output lines use non-default fg
# everywhere and would flood menu detection with false positives.
highlit = (
(ch.reverse != base_reverse)
or (ch.bg != "default")
or ch.bold
)
if is_blank and not highlit:
# plain padding: ignore
pass
elif highlit:
hi_cols.append(x)
if ch.fg in _RED_FGS:
red = True
line_hi_spans.append(_contiguous_spans(hi_cols))
line_red.append(red)
# ---- lines array with blank collapsing ----
lines_out: list[LineEntry] = []
blank_run = False
for y in range(rows):
text = display[y].rstrip()
if text == "":
if not blank_run and lines_out: # collapse; drop leading blanks
lines_out.append("...")
blank_run = True
continue
blank_run = False
sel = bool(line_hi_spans[y])
lines_out.append((y, text, sel))
while lines_out and lines_out[-1] == "...":
lines_out.pop()
# ---- menu items: every highlighted span with its text ----
# Column indices a/b are terminal CELLS, not string indices: a wide
# character (CJK, emoji, fullwidth) is one character but two cells, so
# display[y][a:b] misaligns for any span with a wide character to its
# left. Aggregate over the cell array instead.
menu_items: list[Span] = []
for y in range(rows):
for (a, b) in line_hi_spans[y]:
text = "".join(c.data for c in line_cells[y][a:b]).strip()
menu_items.append(Span(y, a, b, text))
# ---- selected: widest highlighted span, else cursor line ----
selected: Span | None = None
selected_reason: str | None = None
if menu_items:
selected = max(menu_items, key=lambda s: s.col_end - s.col_start)
selected_reason = "reverse_or_bg"
elif not screen.cursor.hidden:
cy = screen.cursor.y
selected = Span(cy, 0, cols, display[cy].rstrip())
selected_reason = "cursor_line"
# ---- status bar: last non-blank row if it sits in the bottom 1-2 rows ----
status_bar: str | None = None
status_bar_row: int | None = None
last_nonblank = None
for y in range(rows - 1, -1, -1):
if display[y].rstrip():
last_nonblank = y
break
if last_nonblank is not None and last_nonblank >= rows - 2:
status_bar = display[last_nonblank].rstrip()
status_bar_row = last_nonblank
# ---- errors: red fg lines or keyword matches ----
errors: list[tuple[int, str, str]] = []
for y in range(rows):
text = display[y].rstrip()
if not text:
continue
if line_red[y]:
errors.append((y, text, "red_fg"))
elif _ERROR_RE.search(text):
errors.append((y, text, "keyword"))
return Snapshot(
size=(rows, cols),
lines=lines_out,
cursor=(screen.cursor.y, screen.cursor.x),
cursor_hidden=bool(screen.cursor.hidden),
selected_line=(selected.row if selected is not None else None),
selected=selected,
selected_reason=selected_reason,
status_bar=status_bar,
status_bar_row=status_bar_row,
title=(screen.title or None),
menu_items=menu_items,
errors=errors,
screen_reverse=base_reverse,
alt_screen=model.alt_screen,
)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |