dwgx/SmartCLI

docs · PyPI
SmartCLI
*Read this in: **English** · 简体中文 · 繁體中文 · 日本語 · 한국어*
**A local Python toolkit for driving, perceiving, and rendering the terminal — three agent skills over one pluggable PTY + pyte core.**
**Let an AI drive, perceive, and render real terminal programs.** SmartCLI reads
the actual screen with a pyte cell model — not a byte pipe — so it knows which
menu row is highlighted, presses the right keys, and waits for the screen to
settle. Below: it drives the real **lazygit** TUI end-to-end (arrow-key
navigation, opening a commit diff, highlighting a branch) — no script, no mock.
Requires Python 3.10 or newer. The install includes the shared Python library,
the persistent TUI driver, and the stdio MCP server.
Drive something in 30 seconds
Copy-paste this. It starts a real Python REPL under a PTY, waits for the prompt
(never a blind sleep), types into it, and reads the screen back:
On Windows use --cmd "py -i -q". Swap the command for vim, htop or
lazygit and the same five verbs drive those too — that is the whole point:
**wait-regex and friends react to what the screen actually shows**, so an agent
never guesses whether its keystroke landed.
Want the same thing against a real editor, end to end and verifiable?
examples/drive_vim.py drives the actual vim binary —
opens a file, appends a line, saves, and then checks the **filesystem**, not the
screen:
Note the fourth step. It is there because the example itself once sent five
keystrokes back to back with nothing between them, and under load vim had not
processed G by the time o arrived, so nothing was inserted and the run failed
with no useful diagnosis. Confirming insert mode proves both keys landed — the
same discipline the tool exists to provide, applied to its own demo.
Run the same file against smartcli-toolkit==0.1.8 and two steps fail — and the
file is *never saved*, because a driver that cannot see the alternate screen
mistimes the :wq. That is why the emulation work below matters: a wrong screen
model does not error, it silently succeeds at nothing.
Already running an MCP client (Claude Code, Cursor, VS Code)? The same verbs are
MCP tools, with the per-session token attached for you:
What & why
SmartCLI is a workspace for terminal work that agents and humans both do: **driving**
interactive terminal programs, **perceiving** what a screen actually shows, and
**rendering** visuals and layouts back out. It is built on one shared, pluggable PTY
backend plus a pyte screen model — chosen over screenshot/vision so a single
structured screen model feeds both perception (read the screen) and rendering
(draw the screen). The PTY layer is intentionally **not** tmux-bound: local dev runs
on Windows via ConPTY (pywinpty), while target programs can run under POSIX ptys
or tmux elsewhere. Three skills sit on that core, each a self-contained tool you run
in place from the checkout.
Driving a real TUI
The demo above is SmartCLI driving **lazygit** — a real full-screen curses app —
through its perceive → act → confirm loop: it reads the pyte cell grid (which
row is selected, the alt-screen diff), moves with arrow keys, opens a commit's
diff, and highlights a branch. Captured by driving the actual program in a Linux
container, not scripted or mocked. A byte-stream matcher like pexpect can't
perceive "which row is highlighted"; a screen model can.
**How we know the perception is right.** A screen model is only useful if it
matches what a real terminal shows, so we measure that instead of asserting it:
identical bytes go to a real **tmux** pane and to our model, and the two cell
grids are diffed. Three suites do it — 34 curated cases, a three-way check that
only trusts a behaviour when **tmux *and* GNU screen agree**, and a generative
fuzz over random VT sequences. That campaign found and fixed **12 emulation bugs**,