agent-tui

🚨 重要：macOS デーモンの回避策と Gemini CLI の使用方法 🚨

この macOS 環境で agent-tui を使用すると、デフォルトのバックグラウンドデーモン化プロセスがクラッシュし、Connection refused (os error 61) エラーが発生します。

agent-tui のコマンドを実行する前に、TTY のハングアップから保護した状態で、必ずデーモンを手動で起動してください。 nohup では不十分です。完全に分離された擬似端末を提供するため、必ず tmux を使用してください。

並列実行に対応するため、デーモンが現在実行されていない場合にのみ、再起動してください。

# Check if daemon is alive, start it in tmux if it is not
if ! agent-tui sessions >/dev/null 2>&1; then
  tmux kill-session -t agent-tui 2>/dev/null || true
  agent-tui daemon stop 2>/dev/null || true
  rm -f /tmp/agent-tui*
  tmux new-session -d -s agent-tui 'agent-tui daemon start --foreground > /tmp/agent-tui-daemon.log 2>&1'
  sleep 1
fi

セッション ID と PID（再接続時に重要）

agent-tui run が JSON を返すと、session_id と pid の両方が含まれています。pid は参考情報にすぎず、子コマンドの OS プロセス ID です。再接続やコマンドの実行に pid は使用しません。必ず session_id（例：--session <id>）を使用してください。

デーモンがクラッシュした場合（os error 61）、擬似端末は破棄されます。子プロセスの pid が孤立プロセスとして存続していても、再接続することはできません。上記の回避策を使ってデーモンを再起動し、まったく新しいセッションを開始してください。

Gemini CLI のテスト

agent-tui で Gemini CLI をテストする場合、動作の決定性と正確性を確保するために、いくつかの厳格な要件があります。

1. 実行前にビルドする：agent-tui は TypeScript ではなく、ビルド済みの JS ファイルを実行します。コードを変更した後、agent-tui で CLI を起動する前に、必ず npm run build または npm run build:all を実行してください。
2. 信頼確認モーダルを回避する：環境変数に GEMINI_CLI_TRUST_WORKSPACE=true を必ず渡してください。そうしないと、新しいプロジェクトレベルのエージェントや拡張機能を追加した際に、全画面表示の「確認して有効にする」モーダルが表示されます。このモーダルがフォーカスを奪い、自動化のキー入力を無視するため、agent-tui wait コマンドがタイムアウトします。
3. 環境を分離する：実際のユーザー認証情報や既存のエージェントの干渉なしにテストする必要がある場合は、GEMINI_CLI_HOME=<some-test-dir> を使ってグローバル設定を分離してください。
4. 状態差分（例：再読み込み）をテストする：「新しいローカルサブエージェントが 1 つあります」と出力する /agents reload のように、差分を報告する機能をテストする場合は、必ず次の手順に従ってください。
   • まず CLI を起動し、初期レジストリを確立します。
   • 別のシェルコマンドを使い（agent-tui の外で）、新しいエージェントの .md／.toml ファイルを書き込みます。
   • agent-tui type と press を使って、実行中のセッション内で /agents reload コマンドを実行します。
   • （CLI の起動前にファイルを追加すると、初期状態の一部になり、差分の検出ロジックが動作しません）。

# Example: Standard isolated run (sandboxed config + bypass trust modals)
env GEMINI_CLI_TRUST_WORKSPACE=true GEMINI_CLI_HOME=test-gemini-home agent-tui run -d "$(pwd)" node packages/cli/dist/index.js

ターミナル自動化を極める

前提条件

• 対応 OS：macOS または Linux（Windows はまだサポートされていません）。
• インストールの確認：

agent-tui --version

インストールされていない場合は、次のいずれかを使用してください。

# Recommended: one-line install (macOS/Linux)
curl -fsSL https://raw.githubusercontent.com/pproenca/agent-tui/master/install.sh | sh

# Package manager
npm i -g agent-tui
pnpm add -g agent-tui
bun add -g agent-tui

# Build from source
cargo install --git https://github.com/pproenca/agent-tui.git --path cli/crates/agent-tui

インストールスクリプトを使用した場合は、~/.local/bin が PATH に含まれていることを確認してください。

基本理念：ターミナル自動化が異なる理由

ターミナル UI は、観測者から見るとステートレスです。永続的な DOM を持つ Web ブラウザーとは異なり、ターミナル自動化では、常に更新される文字グリッドを扱います。この根本的な違いが、あらゆる動作に影響します。

Web 自動化	ターミナル自動化
DOM は操作後も維持される	画面バッファは常に再描画される
セレクターは安定している	テキストの位置は移動することがある
一度クエリすれば、何度でも操作できる	操作する前に毎回、再確認が必要
ネットワークイベントで完了を検知する	視覚的な安定を検知する必要がある

核心となる洞察：agent-tui は、記憶を持たない視覚機能を提供します。スクリーンショットは毎回、新たな観測結果です。UI が変化すると、それ以前の状態は意味を持ちません。これは制限ではなく、ターミナル操作の本質です。

メンタルモデル：フィードバックループ

ターミナル自動化を、閉ループ制御システムとして考えてください。

    ┌──────────────────────────────────────────────┐
    │                                              │
    ▼                                              │
OBSERVE ──► DECIDE ──► ACT ──► WAIT ──► VERIFY ───┘
   │                                        │
   │                                        │
   └─────── NEVER skip ◄────────────────────┘

各フェーズは必須です。 確認を省略することが、不安定な自動化の最大の原因です。

「新鮮な目」の原則

UI を操作する必要があるときは、毎回次の手順に従ってください。

1. 新しいスクリーンショットを撮る — 以前のスクリーンショットは古くなっています
2. 画面を見て対象を特定する — テキストの位置が変わっている場合があります
3. 状態を確認する — UI が予期せず変化している場合があります
4. 安定してから操作する — アニメーションや読み込み中の状態は失敗の原因になります

手間がかかるように感じるかもしれませんが、これが唯一信頼できる方法です。古い状態を楽観的に再利用すると、デバッグが困難な断続的な失敗につながります。

重要なルール（必ず守ること）

ルール 1：アトミックに実行する（パイプライン処理は禁止） && を使ってコマンドを連結することは禁止です（例：type "x" && press Enter && wait）。モーダルや UI の更新によってキー入力が割り込まれることがあります。必ずアトミックな操作を 1 つ実行し、待機してスクリーンショットを撮り、確認してから、次のターンで次の操作を実行してください。

ルール 2：操作のたびにスナップショットを撮り直す どのような変化でも UI の状態は無効になります。次の操作をする前に、必ず新しいスクリーンショットを撮ってください。

ルール 3：不安定な UI は操作しない UI がアニメーション中、読み込み中、または遷移中の場合は、まず wait --stable を実行してください。競合状態が発生するため、遷移中の操作は避けてください。

ルール 4：成功を宣言する前に確認する wait "expected text" --assert を使って、結果を確認してください。操作が成功したと思い込まず、実際に成功したことを確認してください。

ルール 5：エラーからの復旧 wait コマンドがタイムアウトした場合、むやみにセッションを再起動したり終了したりしないでください。screenshot を実行し、モーダル、エラーダイアログ、フォーカスの喪失など、予期しない UI 要素が操作の流れを妨げていないか目視で確認してください。

ルール 6：セッションをクリーンアップする 必ず最後に agent-tui kill を実行してください。孤立したセッションはリソースを消費し、今後の実行に干渉する可能性があります。

判断の枠組み

どのスクリーンショットモードを使うか

自動化の出力を解析する場合は screenshot --format json を、人が読みやすいテキストが必要な場合は通常の screenshot を使ってください。

どのように待機するか

What are you waiting for?
│
├─► Specific text to appear
│   └─► `wait "text" --assert` (fails if not found)
│
├─► Specific text to disappear
│   └─► `wait "text" --gone --assert`
│
├─► UI to stop changing (animations, loading)
│   └─► `wait --stable`
│
└─► Multiple conditions
    └─► Chain waits sequentially

どのように操作するか

What do you need to do?
│
├─► Type text into the terminal
│   └─► `type "text"`
│
├─► Send keyboard shortcuts/navigation
│   └─► `press Ctrl+C` or `press ArrowDown Enter`

基本的なワークフロー

標準的な自動化のループ：

# 1. START: Launch the TUI app
agent-tui run <command> [-- args...]

# 2. OBSERVE: Get current UI state
agent-tui screenshot --format json

# 3. DECIDE: Based on text, determine next action
# (This happens in your head/code)

# 4. ACT: Execute the action
agent-tui type "text"
agent-tui press Enter

# 5. WAIT: Synchronize with UI changes
agent-tui wait "Expected" --assert    # or wait --stable

# 6. VERIFY: Confirm the outcome (often combined with step 5)
# If verification fails, handle the error

# 7. REPEAT: Go back to step 2 until done

# 8. CLEANUP: Always clean up
agent-tui kill

アンチパターン（してはいけないこと）

❌ アニメーション中や読み込み中に操作する

# WRONG: Acting immediately on dynamic UI
agent-tui run my-app
agent-tui screenshot --format json    # UI might still be loading!
agent-tui type "value"                # ❌ Might miss the input field

# RIGHT: Wait for stability first
agent-tui run my-app
agent-tui wait --stable               # Let UI settle
agent-tui screenshot --format json    # Now it's reliable
agent-tui type "value"

❌ 確認せずに成功したと思い込む

# WRONG: Assuming the type worked
agent-tui type "value"
agent-tui press Enter
# ...proceed as if success...       # ❌ What if it failed silently?

# RIGHT: Verify the outcome
agent-tui type "value"
agent-tui press Enter
agent-tui wait "Success" --assert    # ✓ Proves the action worked

❌ クリーンアップを省略する

# WRONG: Forgetting to kill the session
agent-tui run my-app
# ...do stuff...
# script ends                        # ❌ Session left running!

# RIGHT: Always clean up
agent-tui run my-app
# ...do stuff...
agent-tui kill                       # ✓ Clean exit

開始する前に：要件を明確にする

TUI を自動化する前に、次の情報を確認してください。

1. コマンド：具体的に何を実行しますか？（my-app --flag または npm start など）
2. 成功条件：どのテキストや状態が成功を示しますか？
3. 入力手順：どのキーやデータを、どの順番で入力しますか？
4. 安全性：フォームの送信やデータの削除などを行っても安全ですか？
5. 認証：ログインは必要ですか？テスト用の認証情報はありますか？
6. ライブプレビュー：ユーザーは操作を見たいですか？（agent-tui live start --open）

不明な点があれば、実行する前に質問してください。

デモモード：agent-tui でできることを紹介する

ユーザーが agent-tui とは何かを尋ねたり、デモを希望したり、動作を見せてほしいと依頼したりした場合：

1. 説明するのではなく、実演してください。 言葉より行動が雄弁です。
2. ライブプレビューを使って、リアルタイムで見られるようにしてください。
3. top を実行してください — どの環境でも使え、動的なリアルタイム更新を表示できます。

デモをすぐに始めるきっかけとなるフレーズ：

• 「agent-tui とは何ですか？」／「agent-tui では何ができますか？」
• 「agent-tui のデモを見せて」／「agent-tui を見せて」
• 「agent-tui はどのように動作しますか？」／「実際に動くところを見せて」

失敗からの復旧

症状	診断	解決方法
"Text not found"	表示が古いか、テキストが移動しています	スナップショットを撮り直し、テキストを再度特定します
待機がタイムアウトする	UI が期待した状態になっていません	スクリーンショットを確認し、想定した状態を確認します
"Daemon not running"	デーモンがクラッシュしたか、起動していません	agent-tui daemon start
レイアウトが予期しない状態になる	ターミナルのサイズが正しくありません	agent-tui resize --cols 120 --rows 40
セッションが応答しない	アプリがクラッシュしたか、応答しなくなっています	agent-tui kill を実行してから、再実行します
失敗が繰り返される	根本的な問題が発生しています	3～5 回試したら中止し、ユーザーに尋ねてください

自己探索：--help を使う

すべてのフラグを暗記する必要はありません。CLI は自己文書化されています。

agent-tui --help                     # List all commands
agent-tui run --help                 # Options for 'run'
agent-tui screenshot --help          # Options for 'screenshot'
agent-tui wait --help                # Options for 'wait'

迷ったら、CLI に尋ねましょう。 このスキルでは、コマンドを使う「タイミング」と「理由」を説明します。正確なフラグや構文については、--help が正式な情報源です。

クイックリファレンス

# Start app
agent-tui run <cmd> [-- args]        # Launch TUI under control

# Observe
agent-tui screenshot                  # Plain text view
agent-tui screenshot --format json    # Machine-readable output

# Act
agent-tui press Enter                 # Press key(s)
agent-tui press Ctrl+C                # Keyboard shortcuts
agent-tui type "text"                 # Type text

# Wait/Verify
agent-tui wait "text" --assert        # Wait for text, fail if not found
agent-tui wait "text" --gone --assert # Wait for text to disappear
agent-tui wait --stable               # Wait for UI to stop changing

# Manage
agent-tui sessions                    # List active sessions
agent-tui live start --open           # Start live preview
agent-tui kill                        # End current session