SmartCLI — drive terminal TUIs

SmartCLI

こちらの言語でも読めます：英語 · 簡体字中国語 · 繁体字中国語 · 日本語 · 韓国語

端末を操作、認識、レンダリングするためのローカル Python ツールキットです。プラグ可能な PTY + pyte コアを基盤として、3 つのエージェントスキルを提供します。

AI に実際の端末プログラムを操作、認識、レンダリングさせましょう。 SmartCLI はバイトストリームではなく、pyte のセルモデルを使って実際の画面を読み取ります。そのため、どのメニュー項目がハイライトされているかを把握し、適切なキーを押して、画面が落ち着くまで待機できます。以下では、実際の lazygit TUI を最初から最後まで操作します（矢印キーでの移動、コミット差分の表示、ブランチのハイライト）。スクリプトもモックも使いません。

pip install smartcli-toolkit

Python 3.10 以降が必要です。インストールには、共有 Python ライブラリ、永続的な TUI ドライバー、stdio MCP サーバーが含まれます。

30 秒で何かを操作する

これをコピーして貼り付けてください。PTY の下で実際の Python REPL を起動し、プロンプトが表示されるまで待ってから（盲目的な sleep は使いません）、入力して画面を読み取ります。

pip install smartcli-toolkit
SID=$(smartcli-tui start --cmd "python3 -i -q" --cols 80 --rows 24 --json | python3 -c "import json,sys;print(json.load(sys.stdin)['sid'])")
smartcli-tui wait-regex --id $SID ">>> " --timeout-ms 15000
smartcli-tui send-line --id $SID "print(6*7)"
smartcli-tui wait-regex --id $SID "42"          # prints the cell grid it sees
smartcli-tui close --id $SID

Windows では --cmd "py -i -q" を使用してください。コマンドを vim、htop、lazygit に置き換えても、同じ 5 つの動詞で操作できます。これこそがポイントです。wait-regex などは画面に実際に表示された内容に反応するため、エージェントがキー入力を受け付けたかどうかを推測する必要はありません。

実際のエディターで同じ操作を最初から最後まで行い、検証したいですか？ examples/drive_vim.py は実際の vim バイナリを操作します。ファイルを開き、行を追加して保存し、その後、画面ではなくファイルシステムを確認します。

python examples/drive_vim.py
#   [OK ] vim painted its screen
#   [OK ] file contents visible on screen
#   [OK ] alternate screen is active
#   [OK ] vim entered insert mode (so G and o both landed)
#   [OK ] typed text appears on screen
#   [OK ] vim restored the main screen on exit
#   [OK ] file on disk really changed

4 番目の手順に注目してください。この例自体が以前、間に何も挟まず 5 つのキー入力を連続して送信していたため、負荷がかかると o が届くまでに vim が G を処理できず、何も挿入されないまま、役に立つ診断情報もなく実行に失敗したことがありました。挿入モードを確認すれば、両方のキー入力が処理されたことを証明できます。これは、このツールが提供する規律を、ツール自身のデモにも適用したものです。

同じファイルを smartcli-toolkit==0.1.8 で実行すると、2 つの手順が失敗し、ファイルは保存されません。代替画面を認識できないドライバーでは、:wq のタイミングを誤るためです。だからこそ、以下のエミュレーションが重要です。画面モデルが間違っていてもエラーにはならず、何もできていないのに、黙って成功したように見えてしまいます。

すでに MCP クライアント（Claude Code、Cursor、VS Code）を実行していますか？同じ動詞が MCP ツールとして利用でき、セッションごとのトークンも自動で付与されます。

smartcli-mcp        # stdio MCP server; or `uvx --from smartcli-toolkit smartcli-mcp`

概要と目的

SmartCLI は、エージェントと人間の両方が行うターミナル作業のためのワークスペースです。インタラクティブなターミナルプログラムを操作し、画面に実際に表示されている内容を認識し、ビジュアルやレイアウトを描画して出力します。共有可能なプラグイン式の PTY バックエンドと pyte の画面モデルを基盤としており、スクリーンショットや画像認識ではなくこの方式を採用しています。単一の構造化された画面モデルを、認識（画面を読み取る）と描画（画面を描く）の両方に利用できます。PTY レイヤーは意図的に tmux に依存しない設計です。ローカル開発は Windows で ConPTY（pywinpty）を使って実行でき、対象プログラムは別の環境で POSIX pty や tmux の下で実行できます。この基盤の上に 3 つのスキルがあり、それぞれチェックアウト先からその場で実行できる、自己完結型のツールです。

実際の TUI を操作する

上のデモでは、SmartCLI が実際の全画面 curses アプリである lazygit を、認識 → 操作 → 確認のループを通じて操作しています。pyte のセルグリッドを読み取り（選択されている行や、代替画面の差分を確認し）、矢印キーで移動し、コミットの差分を開いて、ブランチをハイライト表示します。スクリプトやモックではなく、Linux コンテナー内で実際のプログラムを操作してキャプチャしたものです。pexpect のようなバイトストリームのマッチャーでは「どの行がハイライトされているか」を認識できませんが、画面モデルなら認識できます。

認識が正確だと分かる理由。 画面モデルは、実際のターミナルに表示される内容と一致して初めて役立つため、正しいと断言するのではなく、それを測定します。同一のバイト列を実際の tmux ペインと私たちのモデルに送り、2 つのセルグリッドの差分を比較します。これを 3 つのテストスイートで実施します。厳選した 34 ケース、tmux と GNU screen の両方が一致する場合のみ挙動を信頼する 3 者間チェック、そしてランダムな VT シーケンスを使った生成的ファズテストです。このテストにより、代替画面バッファーを含む 12 件のエミュレーションバグを発見し、修正しました（pyte はモード 1049／1047／47 をいずれも実装していないため、全画面プログラムの出力がメイン画面に上書きされ、元に戻らない状態でした）。対象範囲と残る課題： LIMITATIONS.md。

ライブエフェクト

cmd-art の fx エンジンによる実際のキャプチャです。各 GIF は、スクリーンレコーダーを使わず、プロジェクト独自のパイプラインでフレームごとにレンダリングした実際のエフェクトです。python -m fx play <name> で再現できます（クイックスタートを参照）。

_{solarsystem — 太陽系模型：脈動する太陽の周りを楕円軌道で公転する惑星}

donut — 定番の ASCII トーラス	fire — デモシーン風の熱場	rain — Matrix 風のデジタルレイン

🌐 ライブショーケースを見る → — エフェクトエンジンを試したり、矢印キーでメニューを操作したり、ウィジェットを試したりできます。すべてブラウザー上で行えます。

インストール

Claude Code スキルを3つだけ使いたいですか？ ZIP を1つダウンロードして解凍するだけで完了です。git、pip、マーケットプレイスは不要です。

curl -LO https://github.com/dwgx/SmartCLI/releases/latest/download/smartcli-skills.zip

unzip smartcli-skills.zip -d ~/.claude/skills/

これで cmd-art、drive-tui、tui-ui を利用できます（合計 309 KiB）。cmd-art と tui-ui は CPython 3.10+ だけで動作します。何も入っていない仮想環境で確認済みで、 30種類すべてのエフェクトと17個すべてのウィジェットが読み込まれます。drive-tui は さらに pyte が必要ですが、以下の PyPI インストールで導入できます。または、 プラグインマーケットプレイスから3つすべてをインストールできます： /plugin marketplace add dwgx/SmartCLI。

推奨 — PyPI からインストール（ライブラリ、CLI、MCP サーバー）：

pip install smartcli-toolkit

配布名とインポート名について： PyPI の配布名は smartcli-toolkit です （smartcli／smart-cli はすでに使用されているか、ブロックされています）が、 インポート可能なパッケージ名は smartcli_core です。そのため、 pip install smartcli-toolkit の後も from smartcli_core import PtySession と 記述します。

代替方法 — ソースチェックアウトから開発環境全体を再現する：

git clone https://github.com/dwgx/SmartCLI SmartCLI
cd SmartCLI
python -m pip install -r requirements.txt

requirements.txt は pyte、MCP SDK、Windows のみ pywinpty をインストールします （POSIX では標準ライブラリの pty バックエンドを使用します）。pip install . は smartcli_core に加えて、smartcli-tui、smartcli-mcp、smartcli-toolkit コマンドを インストールします。ビジュアル系の cmd-art と tui-ui スキルは、チェックアウト先から python -m fx および python -m ui でそのまま実行できます。

任意の追加パッケージ（FIGlet の実フォント、ラスター画像、正確なセル幅。未導入の場合は いずれも標準ライブラリの代替機能に適切にフォールバックします）：

python -m pip install -r requirements-optional.txt
# or, from the checkout, via pyproject extras:
pip install ".[all]"        # pyfiglet + Pillow + wcwidth
pip install ".[art]"        # pyfiglet only
pip install ".[image]"      # Pillow only  (also: the PNG screenshot harness needs it)
pip install ".[width]"      # wcwidth only

Windows に関する注意： ボックス描画文字や CJK グリフを正しくエンコードできるよう、 スキルを実行する前に UTF-8 出力を設定してください（CLI も標準出力を自動で再設定しますが、 念のため設定してください）。

set PYTHONIOENCODING=utf-8

開発用 PC（Windows 11、CPython 3.14.6）で確認済みの依存関係のバージョン： pyte 0.8.2、pywinpty 3.0.5、pyfiglet 1.0.4、Pillow 12.2.0、wcwidth 0.8.1。

診断。 python -m smartcli_core は OS、Python、ターミナル、PTY バックエンド、 依存関係のバージョンを表示します。smartcli-tui doctor は、コアがどこから読み込まれたか、 および drive の依存関係が揃っているかを報告します。ターミナルに依存する不具合を報告する際は、 両方の出力を添付してください。

クイックスタート

cmd-art — ターミナルのビジュアルエフェクト

cd skills/cmd-art
python -m fx list                          # list all 30 effects
python -m fx play donut --seconds 5        # play one effect (bounded)
python -m fx gallery                       # one frame of each effect
python -m fx show --seq "donut:fire:3,plasma::3"

tui-ui — セル単位で正確なターミナル UI

cd skills/tui-ui
python -m ui widgets                       # list all 17 widgets
python -m ui gallery --width 100 --height 30
python -m ui demo table --width 80 --height 12 --theme dashboard

drive-tui — 対話型プログラムの状況把握と操作

永続セッション型 CLI（シェル呼び出し間で状態が保持されます）：

smartcli-tui start --cmd "python3 -i -q" --cols 80 --rows 24
smartcli-tui wait-regex --id <SID> ">>> " --timeout-ms 15000
smartcli-tui send-line --id <SID> "print(6*7)"
smartcli-tui snapshot --id <SID>
smartcli-tui close --id <SID>

Windows では、子コマンドとして py -i -q を使用してください。ソースをチェックアウトした場合は、 smartcli-tui を python skills/drive-tui/scripts/tui.py に置き換えてください。

また、任意の MCP クライアントから操作することもできます。MCP ツールと同じ動詞を使用し、 セッションごとのトークンは自動的に付加されます。

pip install smartcli-toolkit
smartcli-mcp     # stdio MCP server; smartcli-toolkit is an equivalent alias

ライブラリとして使用する

共有コアは直接インポートできます：

import sys
from smartcli_core import PtySession

s = PtySession()
s.start([sys.executable, "-q"])
s.wait_for(r">>> ")            # readiness sync, never a blind sleep
print(s.snapshot().to_text())  # pyte-backed structured screen
s.close()

コマンドの完全なリファレンス、スクリーンショット／AGENTCLI ハーネス、回帰テスト一式については、 README-USAGE.md を参照してください。

特長

cmd-art（skills/cmd-art） — 「リビングテンプレート」効果エンジンです。Effect ABC、@register デコレーター、自動検出で構成されています。30 種類の効果（donut、solarsystem、fire、plasma、rain、starfield、tunnel、text3d、cube、sphere、boids、life、fireworks、sparkle、decrypt、gradient_text、banner_scroll、image2ascii、typewriter、julia、mandelbrot、perlin、flames、water、nebula、text_flyin、text_converge、text_decrypt、spectrum_bars、cbonsai）を8 種類のテーマ（mono、fire、ocean、synthwave、viridis、pastel、matrix-green、rainbow）で利用できます。効果は純粋なフレーム生成器です。play はデフォルトで実行時間が制限され、常にターミナルを元の状態に戻します。

tui-ui（skills/tui-ui） — tmux に安全な ANSI フレーム（SGR カラーランと改行のみ。カーソル移動や代替画面は使いません）を出力する、ウェブ風のターミナルレイアウトエンジンです。エンジンは、レンダリング経路から実際に呼び出される 2 つのモジュール、field.py（シェーダーコンポジター）と raster.py（サブセルの半角／四分割／点字ピクセル）で構成されています。17 種類のウィジェット（badge、banner、braille_chart、card、fuzzy_filter_list、gradient_rule、kv、meter、panel、preview_pane、progress、radial_glow、rule、slider_track、table、tabs、tree）を提供します。さらに 2 つのヘルパー、box_junction.py と color_model.py は、0.3.2 まで未接続のまま同梱されていましたが、何からもインポートされておらず、tui-ui は ui/ を自動検出しないため、呼び出し元から利用できる経路がありませんでした。そのため、0.3.3 で削除されました。CJK／絵文字／ZWJ の表示幅を正確に扱うため、列がずれることはありません。

drive-tui（skills/drive-tui） — PTY 経由で、対話型ターミナルプログラム（REPL、メニュー、ページャー、y/N プロンプト、ウィザード）を操作します。知覚 → 判断 → 実行 → 待機 → 確認のループを使い、無条件にスリープすることはありません。薄い CLI（scripts/tui.py）は、永続的なデタッチセッションと単発の run モードを提供します。また、画面を classify() で分類し、drive() で操作する、インポート可能な8 種類のレシピ（repl、menu_select、pager、search_filter、confirm、form、progress、wizard）のライブラリも備えています。

待機機能の所在。 待機機能群では、残りのタイムアウトを使い切るまで待たずに、子プロセスの終了時点で待機を終了できます。最初の入力でクラッシュするプログラムの場合、タイムアウト全体ではなく、ポーリング 1 回分だけで済みます。この機能はオプトインで、デフォルトでは無効です。start --detect-child-exit／run --detect-child-exit を指定するか、MCP の start ツールで detect_child_exit を指定してください。無効時の動作はこれまでとまったく同じです。有効時は、すべての待機応答に exited が含まれ、wait は reason=EXITED を報告します。そのほかの 3 つのコア機能、画面リビジョンの待機基準、ターミナルモードレジストリ、セッションイベントログは、ライブラリ専用です。smartcli_core からインポートできますが、意図的に CLI や MCP のインターフェースには公開していません。各機能の理由については、CHANGELOG.md の Unreleased を参照してください。

共有コア（smartcli_core） — プラグイン可能な PTY バックエンド、pyte 画面モデル、セマンティックスナップショット、準備完了同期（pty_backend / screen_model / snapshot / readiness / session）で構成されています。3 つすべてのスキルを支える、再利用可能でインポート可能な基盤です。0.3.0 以降、予算制限付きの読み取り経路と io ブロックがすべての観測結果に含まれるため、呼び出し元は 静止中 と まだ読み取られていない 状態を区別できます（local_cut、バイトのウォーターマーク、保留中の事実。未知の値は 0 ではなく null です）。STABLE となるには、観測結果の読み取りが完了している必要があります。また、クローズ時には、ネイティブ呼び出しが返れば子プロセスは終了したと決めつけるのではなく、最後の進行状況とともに closed_confirmed または close_unconfirmed を報告します。

ナレッジグラフ（knowledge/） — 正確なレンダリング式、ANSI シーケンス、実測定数をまとめたウィキリンク形式のグラフ（.md ファイル 140 件以上）です。各ノートには出典と相互リンクが記載されています。knowledge/INDEX.md を参照してください。

プロジェクトの構成

SmartCLI/
  smartcli_core/           shared PTY + pyte engine (importable package)
  skills/cmd-art/          fx effect package and CLI (30 effects, 8 themes)
  skills/drive-tui/        TUI pattern library and PTY driver CLI (8 recipes)
  skills/tui-ui/           terminal UI layout engine and widgets (17 widgets)
  tools/screenshot/        pyte -> PNG smoke-test harness
  tools/agentcli/          agent-CLI control validation harness
  knowledge/               wiki-link knowledge graph, 140+ .md files (see knowledge/INDEX.md)
  showcase/                rendered effect PNGs + demo GIFs (shown above)
  tests/                   direct script-style regressions
  research/                archived first-pass research notes

ドキュメント

• README-USAGE.md — すべてのスキル、スクリーンショットおよび AGENTCLI ハーネス、回帰テスト用コマンドを網羅した使用方法のチートシートです。
• knowledge/INDEX.md — ナレッジグラフ（.md ファイル 140 件以上）です。
• AGENTCLI-VALIDATION.md — エージェント CLI 制御テストのマトリックスです。
• CHANGELOG.md — リリース履歴です。
• 検証エビデンスのツリー — 2026-10-01 にアーカイブ済み。 以前の verification/ ディレクトリ（レシート、プローブ、過去のハーネスの改訂版）は、現在はこのリポジトリに含まれておらず、パッケージにも同梱されていません。バイト単位で移動したため、削除されたものはありません。3 件のバグ修正前に取得した smartcli_core/screen_model.py の古いコピーが 8 個含まれており、リポジトリ全体を検索すると修正前のコードが返されていたため、取り出されました。その中の sha256 ピンは引き続き解決できます — 指し示すファイルはリポジトリに残っています。

ライセンス

MIT — LICENSE を参照してください。