remorses/tuistory

TMUX for agents. let agents control & test terminal user interfaces. Like Playwright & agent-browser but for TUIs

tuistory –「AIエージェントのためのtmux」

それは何か – Node‑JS CLI（およびライブラリ）で、管理されたPTYセッション内で任意のターミナルコマンドを実行します。セッションはバックグラウンドで動作し、AI駆動のエージェントが検査、待機、入力、スクリーンショットを取得できる一方、人間はいつでも同じセッションにアタッチして、エージェントが見ているものを正確に確認できます。

AI/MLにとって重要な理由 – 現在のLLMベースのコーディングエージェントは、開発サーバーやREPLを起動した後、プロセスが準備できるまでポーリングやスリープを行う必要があることがよくあります。tuistoryは、これらのエージェントに決定的でイベント駆動の制御を提供します：

ログを読む（tuistory read）、
特定の出力を待つ（tuistory wait "ready"）、
ターミナル画面のスナップショットまたはスクリーンショットを撮る、
プロセスに文字を入力またはキーを押す、そして
プロセスを再起動/終了する – すべて即座に戻る高速なCLI呼び出しで実現。

仕組み

tuistory -- <command> はバックグラウンドPTYでコマンドを起動し、セッション名を登録します（cwdとコマンドから自動的に派生、例：myapp-next-dev）。
小さなデーモンがすべてのセッションをメモリに保持し、CLIツールやエージェントがPTYと通信するためのローカルWebSocketサーバー（127.0.0.1にバインド）を公開します。
人間はtuistory attachで任意のセッションにアタッチでき、tmux attachのように動作します – ライブ端末を表示し、対話し、Ctrl+Cを2回押してデタッチします。
エージェントは同じCLI（またはプログラムAPI）を使用して、出力の読み取り、パターンの待機、入力、キー押下、スクリーンショット取得などを行います。

主要なCLIコマンド

コマンド	目的
`tuistory -- <cmd>`	新しいセッションを開始（既に存在する場合は再アタッチ）。
`tuistory read -s <name> [--all]`	前回の読み取り以降の新しいstdoutを返す（またはバッファ全体）。
`tuistory wait -s <name> <pattern>`	指定されたテキスト/正規表現が表示されるまでブロック。
`tuistory wait-idle -s <name>`	端末が設定可能な遅延の間沈黙するまでブロック。
`tuistory snapshot -s <name> [--trim]`	現在の画面をプレーンテキストで取得。
`tuistory screenshot -s <name>`	画面をPNG画像として保存。
`tuistory type -s <name> "text"`	キャラクターをプロセスに入力（1文字ずつ）。
`tuistory press -s <name> <key>`	キーまたはコードを送信（例：`ctrl c`）。
`tuistory restart -s <name>`	同じセッションで元のコマンドを再起動。
`tuistory close -s <name>`	プロセスを終了し、セッションを破棄。
`tuistory attach -s <name>`	人間専用のインタラクティブアタッチ（tmuxのような）。
`tuistory sessions`	すべてのアクティブなセッションを一覧表示。

プログラムAPI – 同じ機能がTypeScriptライブラリとして公開されています：

import { launchTerminal } from 'tuistory'
const sess = await launchTerminal({ command: 'claude', cols:150, rows:45 })
await sess.waitForText('Claude Code')
await sess.type('what is 2+2?')
await sess.press('enter')
const out = await sess.read()
sess.close()

APIはCLIを反映しています：type、press、text、read、waitForText、click、closeなど。

LLMベースのコーディングエージェントの典型的なワークフロー

# 1️⃣ ツールをバックグラウンドセッションで開始（例：Web開発サーバー）
tuistory -s dev -- pnpm dev

# 2️⃣ サーバーが "ready" を出力するまで待機
tuistory -s dev wait "ready" --timeout 30000

# 3️⃣ エージェントはさらにアクションを実行可能（例：ブラウザを開く、テストを実行するなど）
# 4️⃣ 人間が何が起こっているか確認したい場合：
#    $ tuistory attach -s dev

すべてのステップはエージェントにとってノンブロッキングであり、任意のsleep呼び出しが不要になります。

インストール

npm install -g tuistory   # グローバルCLI
# またはプロジェクト依存関係として
npm install tuistory

完全なオプションリストはtuistory --helpを実行してください。

誰が使うべきか

LLMオーケストレーションによる自動化（例：Claude Code、Auto‑GPTスタイルのエージェント）を開発し、信頼性の高い端末操作が必要な開発者。
フレーキーなスリープなしでインタラクティブなCLIツール（REPL、デバッガー）をスクリプト化したいテストエンジニア。
バックグラウンドプロセスにtmuxをすでに使用しているが、機械可読なインターフェースを望む人。

関連プロジェクト – tuistoryは作者のtermcast（Raycast風のターミナルUI）とkimaki（TUIを制御するDiscordボットエージェント）を支えています。

ライセンス – MIT。