{
"markdown": "\n\n\n\n# SmartCLI\n\n*Read this in: **English** · [简体中文](docs/i18n/README.zh-Hans.md) · [繁體中文](docs/i18n/README.zh-Hant.md) · [日本語](docs/i18n/README.ja.md) · [한국어](docs/i18n/README.ko.md)*\n\n**A local Python toolkit for driving, perceiving, and rendering the terminal — three agent skills over one pluggable PTY + `pyte` core.**\n\n[](https://pypi.org/project/smartcli-toolkit/)\n[](https://pypi.org/project/smartcli-toolkit/)\n[](https://github.com/dwgx/SmartCLI/actions/workflows/ci.yml)\n[](https://codecov.io/gh/dwgx/SmartCLI)\n[](LICENSE)\n[](https://pypi.org/project/smartcli-toolkit/)\n[](#features)\n[](#install)\n\n**Let an AI drive, perceive, and render real terminal programs.** SmartCLI reads\nthe actual screen with a `pyte` cell model — not a byte pipe — so it knows which\nmenu row is highlighted, presses the right keys, and waits for the screen to\nsettle. Below: it drives the real **lazygit** TUI end-to-end (arrow-key\nnavigation, opening a commit diff, highlighting a branch) — no script, no mock.\n\n
\n \n
\n\n```bash\npip install smartcli-toolkit\n```\n\nRequires Python 3.10 or newer. The install includes the shared Python library,\nthe persistent TUI driver, and the stdio MCP server.\n\n### Drive something in 30 seconds\n\nCopy-paste this. It starts a real Python REPL under a PTY, waits for the prompt\n(never a blind `sleep`), types into it, and reads the screen back:\n\n```bash\npip install smartcli-toolkit\nSID=$(smartcli-tui start --cmd \"python3 -i -q\" --cols 80 --rows 24 --json | python3 -c \"import json,sys;print(json.load(sys.stdin)['sid'])\")\nsmartcli-tui wait-regex --id $SID \">>> \" --timeout-ms 15000\nsmartcli-tui send-line --id $SID \"print(6*7)\"\nsmartcli-tui wait-regex --id $SID \"42\" # prints the cell grid it sees\nsmartcli-tui close --id $SID\n```\n\nOn Windows use `--cmd \"py -i -q\"`. Swap the command for `vim`, `htop` or\n`lazygit` and the same five verbs drive those too — that is the whole point:\n**`wait-regex` and friends react to what the screen actually shows**, so an agent\nnever guesses whether its keystroke landed.\n\nWant the same thing against a real editor, end to end and verifiable?\n[`examples/drive_vim.py`](examples/drive_vim.py) drives the actual `vim` binary —\nopens a file, appends a line, saves, and then checks the **filesystem**, not the\nscreen:\n\n```bash\npython examples/drive_vim.py\n# [OK ] vim painted its screen\n# [OK ] file contents visible on screen\n# [OK ] alternate screen is active\n# [OK ] vim entered insert mode (so G and o both landed)\n# [OK ] typed text appears on screen\n# [OK ] vim restored the main screen on exit\n# [OK ] file on disk really changed\n```\n\nNote the fourth step. It is there because the example itself once sent five\nkeystrokes back to back with nothing between them, and under load `vim` had not\nprocessed `G` by the time `o` arrived, so nothing was inserted and the run failed\nwith no useful diagnosis. Confirming insert mode proves both keys landed — the\nsame discipline the tool exists to provide, applied to its own demo.\n\nRun the same file against `smartcli-toolkit==0.1.8` and two steps fail — and the\nfile is *never saved*, because a driver that cannot see the alternate screen\nmistimes the `:wq`. That is why the emulation work below matters: a wrong screen\nmodel does not error, it silently succeeds at nothing.\n\nAlready running an MCP client (Claude Code, Cursor, VS Code)? The same verbs are\nMCP tools, with the per-session token attached for you:\n\n```bash\nsmartcli-mcp # stdio MCP server; or `uvx --from smartcli-toolkit smartcli-mcp`\n```\n\n## What & why\n\nSmartCLI is a workspace for terminal work that agents and humans both do: **driving**\ninteractive terminal programs, **perceiving** what a screen actually shows, and\n**rendering** visuals and layouts back out. It is built on one shared, pluggable PTY\nbackend plus a `pyte` screen model — chosen over screenshot/vision so a single\nstructured screen model feeds both perception (read the screen) and rendering\n(draw the screen). The PTY layer is intentionally **not** tmux-bound: local dev runs\non Windows via ConPTY (`pywinpty`), while target programs can run under POSIX ptys\nor tmux elsewhere. Three skills sit on that core, each a self-contained tool you run\nin place from the checkout.\n\n## Driving a real TUI\n\nThe demo above is SmartCLI driving **lazygit** — a real full-screen curses app —\nthrough its perceive → act → confirm loop: it reads the `pyte` cell grid (which\nrow is selected, the alt-screen diff), moves with arrow keys, opens a commit's\ndiff, and highlights a branch. Captured by driving the actual program in a Linux\ncontainer, not scripted or mocked. A byte-stream matcher like pexpect can't\nperceive \"which row is highlighted\"; a screen model can.\n\n**How we know the perception is right.** A screen model is only useful if it\nmatches what a real terminal shows, so we measure that instead of asserting it:\nidentical bytes go to a real **tmux** pane and to our model, and the two cell\ngrids are diffed. Three suites do it — 35 curated cases, a three-way check that\nonly trusts a behaviour when **tmux *and* GNU screen agree**, and a generative\nfuzz over random VT sequences. That campaign found and fixed **12 emulation bugs**,\nincluding the alternate screen buffer (`pyte` implements none of modes\n1049/1047/47, so a full-screen program's output used to be painted over the main\nscreen and never restored). Scope and remaining edges:\n[`LIMITATIONS.md`](skills/drive-tui/references/LIMITATIONS.md).\n\n## Live effects\n\nReal captures of the `cmd-art` `fx` engine — each GIF is the actual effect\nrendered frame-by-frame through the project's own pipeline (no screen recorder).\nReproduce any with `python -m fx play ` (see [Quickstart](#quickstart)).\n\n
\n \n solarsystem — an orrery: planets on elliptical orbits around a pulsing sun\n
\n\n| | | |\n|:---:|:---:|:---:|\n|  |  |  |\n| **donut** — the classic ASCII torus | **fire** — demoscene heat field | **rain** — Matrix digital rain |\n\n> 🌐 **[Explore the live showcase →](https://dwgx.github.io/SmartCLI/)** — play with\n> the effect engine, drive a menu with arrow keys, and poke the widgets, right in\n> your browser.\n\n## Install\n\n**Just want the three Claude Code skills?** Download one zip, unzip it, done — no\ngit, no pip, no marketplace:\n\n```bash\ncurl -LO https://github.com/dwgx/SmartCLI/releases/latest/download/smartcli-skills.zip\n```\n\n```bash\nunzip smartcli-skills.zip -d ~/.claude/skills/\n```\n\nThat gives you `cmd-art`, `drive-tui` and `tui-ui` (309 KiB total). `cmd-art` and\n`tui-ui` then work with nothing but CPython 3.10+ — verified on a bare virtualenv,\nall 30 effects and all 17 widgets load. `drive-tui` additionally needs `pyte`, which\nthe PyPI install below provides. Or install all three via the plugin marketplace:\n`/plugin marketplace add dwgx/SmartCLI`.\n\n**Primary — from PyPI (the library, the CLI, and the MCP server):**\n\n```bash\npip install smartcli-toolkit\n```\n\n> **Distribution vs import name:** the PyPI distribution is `smartcli-toolkit`\n> (the names `smartcli` / `smart-cli` were taken or blocked), but the importable\n> package is `smartcli_core`. So after `pip install smartcli-toolkit` you still\n> write `from smartcli_core import PtySession`.\n\n**Alternative — reproduce the full dev environment from a source checkout:**\n\n```bash\ngit clone https://github.com/dwgx/SmartCLI SmartCLI\ncd SmartCLI\npython -m pip install -r requirements.txt\n```\n\n`requirements.txt` installs `pyte`, the MCP SDK, and `pywinpty` on Windows only\n(POSIX uses the stdlib `pty` backend). `pip install .` installs `smartcli_core`\nplus the `smartcli-tui`, `smartcli-mcp`, and `smartcli-toolkit` commands. The\nvisual `cmd-art` and `tui-ui` skills still run in place from a checkout via\n`python -m fx` and `python -m ui`.\n\n**Optional extras** (real FIGlet fonts, raster images, authoritative cell widths — all\ndegrade gracefully to stdlib fallbacks when absent):\n\n```bash\npython -m pip install -r requirements-optional.txt\n# or, from the checkout, via pyproject extras:\npip install \".[all]\" # pyfiglet + Pillow + wcwidth\npip install \".[art]\" # pyfiglet only\npip install \".[image]\" # Pillow only (also: the PNG screenshot harness needs it)\npip install \".[width]\" # wcwidth only\n```\n\n**Windows note:** set UTF-8 output before running any skill so box-drawing and CJK\nglyphs encode cleanly (the CLIs also auto-reconfigure stdout, but set this to be safe):\n\n```powershell\nset PYTHONIOENCODING=utf-8\n```\n\nVerified dep versions on the dev box (Windows 11, CPython 3.14.6): `pyte` 0.8.2,\n`pywinpty` 3.0.5, `pyfiglet` 1.0.4, `Pillow` 12.2.0, `wcwidth` 0.8.1.\n\n**Diagnostics.** `python -m smartcli_core` prints your OS, Python, terminal, PTY\nbackend, and dependency versions. `smartcli-tui doctor` reports where the core\nwas loaded from and whether drive dependencies are present. Include both outputs\nwhen filing a terminal-sensitive bug.\n\n## Quickstart\n\n### cmd-art — terminal visual effects\n\n```bash\ncd skills/cmd-art\npython -m fx list # list all 30 effects\npython -m fx play donut --seconds 5 # play one effect (bounded)\npython -m fx gallery # one frame of each effect\npython -m fx show --seq \"donut:fire:3,plasma::3\"\n```\n\n### tui-ui — cell-accurate terminal UI\n\n```bash\ncd skills/tui-ui\npython -m ui widgets # list all 17 widgets\npython -m ui gallery --width 100 --height 30\npython -m ui demo table --width 80 --height 12 --theme dashboard\n```\n\n### drive-tui — perceive & drive interactive programs\n\nPersistent-session CLI (state survives across shell calls):\n\n```bash\nsmartcli-tui start --cmd \"python3 -i -q\" --cols 80 --rows 24\nsmartcli-tui wait-regex --id \">>> \" --timeout-ms 15000\nsmartcli-tui send-line --id \"print(6*7)\"\nsmartcli-tui snapshot --id \nsmartcli-tui close --id \n```\n\nOn Windows use `py -i -q` as the child command. From a source checkout, replace\n`smartcli-tui` with `python skills/drive-tui/scripts/tui.py`.\n\nOr drive from any MCP client — the same verbs as MCP tools, with the\nper-session token attached automatically:\n\n```bash\npip install smartcli-toolkit\nsmartcli-mcp # stdio MCP server; smartcli-toolkit is an equivalent alias\n```\n\n### As a library\n\nThe shared core is importable directly:\n\n```python\nimport sys\nfrom smartcli_core import PtySession\n\ns = PtySession()\ns.start([sys.executable, \"-q\"])\ns.wait_for(r\">>> \") # readiness sync, never a blind sleep\nprint(s.snapshot().to_text()) # pyte-backed structured screen\ns.close()\n```\n\nFor the full command reference, the screenshot/AGENTCLI harnesses, and the regression\nsuite, see **[`README-USAGE.md`](README-USAGE.md)**.\n\n## Features\n\n**`cmd-art`** (`skills/cmd-art`) — a \"living-template\" effect engine: an `Effect` ABC +\n`@register` decorator + auto-discovery. **30 effects** (donut, solarsystem, fire, plasma,\nrain, starfield, tunnel, text3d, cube, sphere, boids, life, fireworks, sparkle, decrypt,\ngradient_text, banner_scroll, image2ascii, typewriter, julia, mandelbrot, perlin, flames, water, nebula, text_flyin, text_converge, text_decrypt, spectrum_bars, cbonsai) across **8 themes** (mono, fire,\nocean, synthwave, viridis, pastel, matrix-green, rainbow). Effects are pure frame\nproducers; `play` is bounded by default and always restores the terminal.\n\n**`tui-ui`** (`skills/tui-ui`) — a web-like terminal layout engine emitting tmux-safe\nANSI frames (SGR color runs + newlines only; no cursor moves, no alt-screen). **17\nwidgets** (badge, banner, braille_chart, card, fuzzy_filter_list, gradient_rule, kv,\nmeter, panel, preview_pane, progress, radial_glow, rule, slider_track, table, tabs,\ntree) over a real **engine**:\n`field.py` (shader compositors), `raster.py` (sub-cell half/quad/braille pixels),\n`box_junction.py` (edge-algebra box joins), `color_model.py` (honest truecolor → 256 →\n16 → mono degrade). Display-cell accurate for CJK/emoji/ZWJ so columns never desync.\n\n**`drive-tui`** (`skills/drive-tui`) — drives interactive terminal programs (REPLs,\nmenus, pagers, y/N prompts, wizards) through a PTY via a\nperceive → decide → act → wait → confirm loop, never a blind sleep. A thin CLI\n(`scripts/tui.py`) offers a persistent detached session and a one-shot `run` mode, with\nan importable pattern library of **8 recipes** (repl, menu_select, pager, search_filter,\nconfirm, form, progress, wizard) that `classify()` a screen and `drive()` it.\n\n**Shared core** (`smartcli_core`) — the pluggable PTY backend + `pyte` screen model +\nsemantic snapshot + readiness sync (`pty_backend / screen_model / snapshot / readiness /\nsession`). The reusable, importable foundation under all three skills.\n\n**Knowledge graph** (`knowledge/`) — a wiki-link graph (140+ `.md` files) of exact\nrendering formulas, ANSI sequences, and measured constants, each note carrying a\nsource and cross-links. See [`knowledge/INDEX.md`](knowledge/INDEX.md).\n\n## Project layout\n\n```text\nSmartCLI/\n smartcli_core/ shared PTY + pyte engine (importable package)\n skills/cmd-art/ fx effect package and CLI (30 effects, 8 themes)\n skills/drive-tui/ TUI pattern library and PTY driver CLI (8 recipes)\n skills/tui-ui/ terminal UI layout engine and widgets (17 widgets)\n tools/screenshot/ pyte -> PNG smoke-test harness\n tools/agentcli/ agent-CLI control validation harness\n knowledge/ wiki-link knowledge graph, 140+ .md files (see knowledge/INDEX.md)\n showcase/ rendered effect PNGs + demo GIFs (shown above)\n tests/ direct script-style regressions\n research/ archived first-pass research notes\n```\n\n## Documentation\n\n- **[`README-USAGE.md`](README-USAGE.md)** — the full usage cheat-sheet: every skill,\n the screenshot and AGENTCLI harnesses, and the regression commands.\n- **[`knowledge/INDEX.md`](knowledge/INDEX.md)** — the knowledge graph (140+ `.md` files).\n- **[`AGENTCLI-VALIDATION.md`](AGENTCLI-VALIDATION.md)** — agent-CLI control test matrix.\n- **[`CHANGELOG.md`](CHANGELOG.md)** — release history.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
"bytes": 15543,
"sha": "adfbb12c1a6a00df407a3793249044722c1d07187ee0c6fde525ddda69e01e12",
"repo_slug": "dwgx/smartcli",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_dwgx_smartcli_102fc568/readme"
}
![\"SmartCLI](\"showcase/drive-lazygit.gif\")
\n![\"ASCII](\"showcase/fx-solarsystem.gif\")