zsh-tool

zsh-tool

Claude Code 向けの zsh 実行ツールです。Bash との完全な互換性、yield ベースの監視、PTY モード、NEVERHANG サーキットブレーカー、A.L.A.N. による短期学習を備えています。

ステータス： ベータ（v0.7.2）

作者： Claude + Meldrey

ライセンス： MIT

組織： ArkTechNWA

---

信頼性に徹底的にこだわって構築されています。

---

なぜ？

最大の理由： zsh を使っている場合、Claude Code の Bash ツールでは引用符の不一致やシェルの混乱が起こります。デバッグのたびにトークンを消費します。zsh-tool なら、これをすぐに、そして恒久的に解消できます。

トークンの節約効果： デバッグの泥沼を一度回避するだけで、30 秒以上を節約し、数百トークンを温存できます。

zsh-tool はインテリジェントなシェル実行を実現します。

問題	zsh-tool による解決策
Bash と zsh の引用符の混乱	ネイティブ zsh — シェルの不一致もデバッグの繰り返しもありません
コマンドがいつまでも停止する	yield ベースの実行 — 常に制御を取り戻せます
実行中のコマンドが見えない	zsh_poll — 出力を段階的に収集できます
プロンプトを操作できない	PTY モード + zsh_send — インタラクティブ操作を完全にサポートします
パスワードを入力できない	PTY モード — Claude Code が自身でパスワードを入力できます
タイムアウトが連鎖する	NEVERHANG サーキットブレーカー — 迅速に失敗し、自動復旧します
呼び出し間で記憶がない	A.L.A.N. 2.0 — リトライ検出、連続状況の追跡、先回りした分析情報
ポーリングでトークンを浪費する	インテリジェントなポーリング — 2 秒の待機時間、状況に応じた提案、所要時間の推定
状況がわからないまま強制終了し、学習もしない	終了を考慮する A.L.A.N. — 焦りによる終了と実際のハングを分類します
間違ったフラグでリトライする	manopt — 失敗が繰り返された場合にコマンドのオプションを自動表示します
タスク管理ができない	zsh_tasks、zsh_kill — 完全に制御できます

これが「コマンドを実行する」ことと「インテリジェントなシェル統合」の違いです。

---

機能

Yield ベースの実行

コマンドは、実行中の場合、部分的な出力を返して yield_after 秒後に戻ります。

• ハングとは無縁 — 常に制御を取り戻せます
• 段階的な出力 — zsh_poll で収集できます
• インタラクティブな入力 — zsh_send で送信できます
• タスク管理 — zsh_kill と zsh_tasks

PTY モード

インタラクティブなプログラム向けの完全な疑似ターミナルエミュレーション：

# Enable with pty: true
zsh(command="pass insert mypass", pty=true)
# See prompts, send input with zsh_send

• インタラクティブなプロンプトを適切に処理します
• TTY を必要とするプログラムに対応します
• 色付きの出力とターミナルのエスケープシーケンスに対応します
• stdin/stdout/stderr を完全に統合します

NEVERHANG サーキットブレーカー

コマンドのハングによってセッションがブロックされるのを防ぎます。

• コマンドハッシュごとにタイムアウトのパターンを追跡します
• 1 時間のローリングウィンドウ内でタイムアウトが 3 回発生すると、サーキットを開きます
• 5 分後に自動復旧します
• 状態：CLOSED（通常）→ OPEN（ブロック中）→ HALF_OPEN（テスト中）

A.L.A.N. 2.0（必要なだけ）

インテリジェントな短期学習 — 「やらかしてるのかもしれないし、うまくやってるのかもしれない」

• リトライ検出 — 失敗したコマンドを繰り返していると警告します
• 連続状況の追跡 — 成功が続くと称賛し、失敗が続くと警告します
• あいまい一致 — git push origin feature-1 → git push origin *
• 先回りした分析情報 — コマンド実行前に状況に応じたフィードバックを提供します
• セッションメモリ — 15 分間のローリングウィンドウで最近のアクティビティを追跡します
• 時間経過による減衰 — 指数減衰（半減期 24 時間）し、自動的に古い情報を削除します
• SSH インテリジェンス — ホストへの接続状況とリモートコマンドの成功を分けて判断します
• パイプラインセグメントの追跡 — cat foo | grep -badopts | sort が失敗した場合、A.L.A.N. は失敗したセグメントを特定します

行番号付き差分出力（v0.6.3）

zsh_poll は、グローバル行番号を付けて、前回のポーリング以降の新しい出力のみを返します。ポーリングのたびに800行を丸ごと出力する必要はもうありません。

801: Installing package foo...
802: Compiling module bar...
803: Done.

フィールド	説明
from_line / to_line	この差分の行範囲（例：801-803）
new_bytes	前回のポーリング以降の新しい出力のバイト数
full_output（パラメーター）	true を渡すと、行番号付きのバッファ全体を取得します

最初のポーリングでは、1行目からすべての出力が返されます。以降のポーリングでは、前回の続きから出力されます。完了したタスクでは最後の差分が返され、その後に再ポーリングすると空になります。

インテリジェントなポーリング

zsh_poll は、結果を返す前に2秒間の待機時間を設けます。2秒以内に出力が届くと、すぐに返されます。届かない場合、ポーリングのメタデータからエージェントは状況を把握できます。

フィールド	説明
polls_since_output	出力のないポーリングが連続した回数
elapsed_since_last_output_s	最後の出力からのアイドル時間
alan_estimate	コマンド履歴に基づくA.L.A.N.の所要時間予測
suggestion	ポーリング間隔を空ける、すぐに確認する、または終了を検討するといった適応型のアドバイス

提案はあくまで参考であり、判断は常にエージェントが行います。2分かかるpip installでも、空の往復が40回発生することはありません。

終了を考慮するA.L.A.N.

エージェントがコマンドを終了すると、A.L.A.N.はその結果をKILLEDとして記録し、終了した理由を分類します。

カテゴリ	意味	例
EARLY_KILL	完了時間の中央値よりかなり前に終了	「30秒で終了。中央値は120秒です。もう少し時間が必要です。」
LATE_KILL	想定時間を大幅に超過して実行	「180秒後に終了。中央値は45秒です。何か問題があります。」
PATTERN_PROBLEM	テンプレートが50%を超える頻度で終了される	「このパターンには、まったく別のアプローチが必要かもしれません。」

終了の分類では、焦りによる終了と実際のハングを区別するため、kill_elapsed / median_durationを比較します。

manopt — 失敗時のmanページオプション

コマンドが繰り返し失敗すると、A.L.A.N.は利用可能なオプションを提示します。

• 1回目の失敗 — 通常のフィードバック。manoptは表示されません
• 2回目の失敗 — バックグラウンドで非同期のmanopt検索を開始します（タイムアウトは2秒）
• 3回目以降の失敗 — A.L.A.N.のインサイトにキャッシュ済みのオプション表を表示します

ローカルのmanページから解析されます。SQLiteにキャッシュされます。デフォルトで有効です（ALAN_MANOPT_ENABLED=1）。

SSHの追跡

A.L.A.N.はSSHコマンドを特別に扱い、2つの異なる観測結果を記録します。

観測対象	追跡内容	インサイトの例
ホスト接続性	このホストに接続できるか	「ホスト'vps'の接続失敗率は67%です」
リモートコマンド	このコマンドはホスト間で動作するか	「リモートコマンド'git pull'は3台のホストで安定して動作します」

終了コードの分類：

• 0 — 成功（接続とコマンドの両方に成功）
• 255 — 接続失敗（SSHで接続できなかった）
• 1-254 — コマンド失敗（接続は成功したが、リモートコマンドが失敗した）

つまり、ssh host3 'git pull'が終了コード255で失敗した場合、A.L.A.N.はgit pullに問題があるのではなく、ホストに到達できなかったと判断します。

---

ツール

ツール	目的
zsh	実行を中断しながら監視してコマンドを実行
zsh_poll	実行中のタスクから、行番号付きで新しい出力（差分）を取得
zsh_send	タスクの標準入力にデータを送信
zsh_kill	実行中のタスクを終了
zsh_tasks	アクティブなタスクをすべて一覧表示
zsh_health	全体的なヘルス状態
zsh_alan_stats	A.L.A.N.データベースの統計情報
zsh_alan_query	コマンドのパターンに関するインサイトを照会
zsh_neverhang_status	サーキットブレーカーの状態
zsh_neverhang_reset	サーキットをCLOSEDにリセット

---

インストール

マーケットプレイスから（推奨）

Claude CodeにArkTechNWAマーケットプレイスを追加します。

ArkTechNWA/claude-plugins

次にインストールします：/plugin install arktechnwa/zsh-tool

これだけです。 プラグインは初回実行時に依存関係を自動インストールします。

手動インストール

git clone https://github.com/ArkTechNWA/zsh-tool.git ~/.claude/plugins/zsh-tool

~/.claude/settings.json で有効にします：

{
  "enabledPlugins": {
    "zsh-tool": true
  }
}

同梱の scripts/run-mcp.sh は、初回実行時に Rust バイナリをビルドして MCP サーバーを起動します。

ローカル開発

ローカルで開発やテストを行う場合、ラッパースクリプトは CLAUDE_PLUGIN_ROOT が展開されていないことを自動的に検出し、代わりに算出したプラグインのルートディレクトリを使用します。設定を変更する必要はありません。

または、絶対パスを指定した .mcp.local.json を作成します：

{
  "mcpServers": {
    "zsh-tool": {
      "type": "stdio",
      "command": "/path/to/zsh-tool/scripts/run-mcp.sh",
      "env": {
        "NEVERHANG_TIMEOUT_DEFAULT": "120",
        "NEVERHANG_TIMEOUT_MAX": "600"
      }
    }
  }
}

明示的に指定されていない場合、ALAN_DB_PATH は {plugin_root}/data/alan.db に自動設定されます。

要件： Rust ツールチェーン（cargo）と zsh がインストールされている必要があります。

---

アーキテクチャ

zsh-tool/
├── .claude-plugin/
│   ├── plugin.json
│   └── CLAUDE.md
├── .mcp.json
├── zsh-tool-rs/
│   ├── Cargo.toml
│   └── src/
│       ├── main.rs          # CLI entry point
│       ├── lib.rs           # Module exports
│       ├── executor.rs      # Pipe/PTY command execution
│       ├── config.rs        # User config (~/.config/zsh-tool/)
│       ├── circuit.rs       # NEVERHANG circuit breaker
│       ├── meta.rs          # Task metadata (exit code, pipestatus)
│       ├── alan/            # A.L.A.N. 2.0 learning engine
│       │   ├── mod.rs       #   Recording + insights
│       │   ├── hash.rs      #   Fuzzy command hashing
│       │   ├── insights.rs  #   Proactive feedback
│       │   ├── manopt.rs    #   Man-page option parsing
│       │   ├── ssh.rs       #   SSH host/command tracking
│       │   ├── streak.rs    #   Success/failure streaks
│       │   ├── pipeline.rs  #   Pipeline segment tracking
│       │   ├── prune.rs     #   Temporal decay + pruning
│       │   └── stats.rs     #   Database statistics
│       └── serve/           # MCP JSON-RPC server
│           ├── mod.rs       #   Request dispatch + tool handlers
│           ├── format.rs    #   Rich output formatting
│           ├── protocol.rs  #   JSON-RPC framing
│           └── tools.rs     #   Tool schema definitions
├── scripts/
│   └── run-mcp.sh           # Build + launch wrapper
├── data/
│   └── alan.db              # A.L.A.N. SQLite database
└── README.md

---

設定

環境変数（.mcp.json で設定）：

• ALAN_DB_PATH — A.L.A.N. データベースの場所
• NEVERHANG_TIMEOUT_DEFAULT — デフォルトのタイムアウト（120s）
• NEVERHANG_TIMEOUT_MAX — 最大タイムアウト（600s）
• ALAN_MANOPT_ENABLED — 失敗時に man ページのオプションヒントを有効にする（デフォルト：1）
• ALAN_MANOPT_TIMEOUT — manopt の解析を待つ最大秒数（デフォルト：2.0）
• ALAN_MANOPT_FAIL_TRIGGER — 非同期検索を開始する失敗回数（デフォルト：2）
• ALAN_MANOPT_FAIL_PRESENT — キャッシュ済みオプションを提示する失敗回数（デフォルト：3）

Bash を無効にする（任意）

zsh のみをシェルとして使用するには、~/.claude/settings.json に追加します：

{
  "permissions": {
    "deny": ["Bash"]
  }
}

---

変更履歴

0.7.2

ユーザーに表示される出力 — モデルに作業内容を示すよう指示

• 修正： Claude Code では MCP ツールの結果がユーザーに表示されません（プラットフォームの制限）。ツールの説明で、コマンド出力を応答テキストにそのまま含めるようモデルに指示するようになりました。
• Claude Code が MCP ツールの結果ブロックをユーザーに表示しない問題への回避策です。

0.7.1

古いバイナリの修正 — 新しい形式を確実に適用

• 修正： ソースに変更がある場合、再ビルド前に run-mcp.sh が cargo clean -p を実行するようになりました。Cargo のインクリメンタルビルドによって古いバイナリが使われるのを防ぎます。
• 修正： 再ビルドのトリガーで Cargo.toml も監視するようになりました（バージョンの更新は、以前の find -newer チェックでは検出できませんでした）。

0.7.0

リッチな出力フォーマット — JSON の羅列はもう不要

• 構造化された出力 — コマンドヘッダー、区切り線で分けたセクション、アイコン付きのステータスフッター
• 視認性の高いステータスアイコン — [COMPLETED / [FAILED の括弧表記を ✔ / ✘ に置き換え
• 進捗表示の集約 — 連続する進捗行（例：10%、20%、30%）を最後の行だけにまとめ、ダウンロードやビルド中に画面が埋まるのを防止
• コマンドの表示 — $ command ヘッダーに実行内容を表示し、120 文字で切り捨て
• 色付きの終了コード — 0 は緑、ゼロ以外は赤、シグナル（129 以上）は黄
• 通知の改善 — バックグラウンドタスクの完了通知に ┌ notify: を使用し、失敗時は色を付けて表示
• ALAN のインサイトアイコン — 警告には ⚠、情報には ℹ を使用
• 新しい format.rs モジュール — すべてのフォーマット処理を mod.rs から切り出し、独立してテスト可能なモジュールに分離
• 新たに 35 件のテスト（合計 121 件）。すべてのフォーマット関数をカバー

0.6.1

プロトコルの修正 — Claude Code v2.1 以降でのプレーンな JSON-RPC 対応

• 修正： MCP サーバーが、Content-Length フレーミングと改行区切りのプレーンな JSON（Claude Code v2.1.42 以降）を自動判別するようになりました。
• デバッグログ： プロトコルのネゴシエーション、リクエスト／レスポンスのライフサイクル、シャットダウンの診断情報を stderr に出力
• ログファイル： MCP のデバッグ用に、run-mcp.sh が stderr を /tmp/zsh-tool-mcp.log にリダイレクト

0.6.0

Rust による全面書き換え — Python に別れを告げ、速度を手に入れる

• Rust で全面的に書き換え — MCP サーバー、実行機能、A.L.A.N.、NEVERHANG をすべてネイティブ化
• Rust テスト 79 件 — ユニットテストと完全な MCP 統合テスト（JSON-RPC のラウンドトリップ）
• CI パイプラインを刷新 — pytest と ruff を cargo test と cargo clippy に置き換え
• Python を削除 — 7,600 行以上の Python コードを削除し、Python 依存関係をゼロに
• CI が約 2 倍高速化 — クリーンビルドは 97s からキャッシュ利用時の 48s に短縮（Python では 60～120s）
• すべての機能を維持：yield/poll/send/kill、PTY モード、A.L.A.N. 2.0、NEVERHANG、manopt、SSH トラッキング、パイプラインの各セグメント

0.5.0

A.L.A.N. v2 アップグレード — インテリジェントなポーリング、kill の認識、manopt

• インテリジェントなポーリング：zsh_poll の 2 秒間のリッスンウィンドウにより、空のラウンドトリップを削減します。所要時間の推定値と適応型の提案を含むポーリングメタデータを提供します
• kill を認識する A.L.A.N.：経過時間の追跡機能を備えた KILLED アウトカムタイプを追加しました。早すぎる kill（せっかちさ）、遅すぎる kill（実際のハング）、パターンの問題（誤ったアプローチ）を分類します
• manopt の統合：コマンドの失敗が繰り返された場合、man ページのオプションを非同期で解析します。SQLite にキャッシュされ、同じコマンドテンプレートで 3 回目以降の失敗時に表示されます
• 観測データに outcome_type 列と kill_elapsed_ms 列を追加しました
• man ページのオプションを永続的に保存する manopt_cache テーブルを追加しました
• 環境変数：ALAN_MANOPT_ENABLED、ALAN_MANOPT_TIMEOUT、ALAN_MANOPT_FAIL_TRIGGER、ALAN_MANOPT_FAIL_PRESENT

0.4.90

フィードバックの改善 — シグナルの質を高め、ノイズを減らす

• ALAN のインサイトを info/warning のタプルとして分類するようになりました
• コマンドの認識：grep の終了コード 1 は「一致なし」（info）、終了コード 127 は「コマンドが見つかりません」（warning）として扱います
• 実行後のインサイト：無出力の検出、パイプによるマスキングの警告、SIGPIPE の除外
• メタデータ行に ANSI カラーを適用（緑＝成功、赤＝失敗、水色＝実行中、黄＝タイムアウト）
• 終了コードに基づいて COMPLETED/FAILED のステータスワードを表示
• 書式化された [cmd:code] 文字列を、生の pipestatus リストに置き換えました
• インサイトをグループ化して表示：[info: A.L.A.N.: ...] および [warning: A.L.A.N.: ...]

0.4.83

Python 3.14 サポート — 将来への対応

• Python 3.14 の分類子とバッジを追加しました
• 非推奨の asyncio.DefaultEventLoopPolicy フィクスチャを削除しました（3.16 で削除予定）
• Python 3.14.2 ですべての 331 件のテストが成功します

0.4.81

Pipestatus マーカーの漏出を修正 — データの完全性

• ___ZSH_PIPESTATUS_MARKER___ が出力に漏れる可能性のある競合状態を修正しました
• 呼び出し元に返す前に、_build_task_response() でマーカーを除去するようになりました
• 実行中に出力をキャプチャした際の、ファイル内容の破損を防ぎます
• CI：Runner を docker executor に切り替え、PEP 668 への準拠を追加しました

0.4.80

セグメントごとの終了コード — どのコマンドが失敗したかを正確に把握

• 終了コードを単一の整数ではなく、[cmd1:0,cmd2:1,cmd3:0] 形式で表示するようになりました
• 各パイプラインセグメントに、zsh の $pipestatus から取得した実際の終了ステータスを対応付けます
• A.L.A.N. の学習で、コマンドごとの正確な結果を使用します
• 人間と AI による分析に適した、自己説明的な出力
• 実際のステータスに関係なく、すべてのコマンドが exit=0 と報告されるバグを修正しました

0.4.79

サーバーのモジュール分割リファクタリング — よりクリーンなアーキテクチャ

• MCP サーバーを zsh_tool/server.py モジュールに切り出しました
• 設定を zsh_tool/config.py に集約しました
• plugin.json のバージョンとパッケージのバージョンが一致するよう修正しました

0.4.75

パイプラインインテリジェンス — パイプラインのどのセグメントが失敗しているかを把握

• A.L.A.N. がすべてのパイプラインについて、zsh の $pipestatus 配列を取得するようになりました
• 各セグメントを、独自の終了コードを持つ独立した観測データとして記録します
• cat foo | grep -badopts | sort が失敗した場合、問題が grep にあると分かります
• 引用符とエスケープを考慮したパイプライン解析により、複雑なコマンドを正しく処理します
• 後方互換性を維持：セグメントに加えて、パイプライン全体も記録します
• セグメント追跡とエッジケースを対象とするテストを 248 行追加しました

0.4.6

設定と仕上げ — ユーザーが設定できるデフォルト値、カバレッジ 91％

• yield_after をカスタマイズするユーザー設定ファイル（~/.config/zsh-tool/config.yaml）
• テストカバレッジを改善：303 件のテスト、カバレッジ 91％
• タスクのクリーンアップにおける null チェックのバグを修正しました
• ロゴファイルを統合し、問題を修正しました

0.4.5

同梱プラグイン — 手間なくマーケットプレイスからインストール

• 自動インストールラッパー（scripts/run-mcp.sh）が初回実行時に venv を作成します
• ${CLAUDE_PLUGIN_ROOT} を使用するポータブルな .mcp.json
• ArkTechNWA マーケットプレイスをサポート
• 手動での pip install は不要です

0.4.0

テストスイートと CI — 290 件のテスト、カバレッジ 89%

• すべてのモジュールを網羅する包括的なテストスイート
• テストと lint の各ステージを含む CI パイプライン
• 動的なパイプラインおよびカバレッジバッジ
• ファイル間で nice と sleep を実行する、穏やかなテストランナー（run_tests.sh）
• 非推奨警告と lint エラーを修正
• 非同期テストをサポートするため pytest-asyncio を追加

0.3.1

SSH インテリジェンス — ホストへの接続とリモートコマンドの成功を分けて記録

• SSH コマンドでホストとリモートコマンドの二重の観測を記録するようになりました
• 終了コードの分類：0=成功、255=接続失敗、1-254=コマンド失敗
• SSH 専用の追跡用に新しい ssh_observations テーブルを追加
• get_ssh_host_stats() — ホストごとの接続／コマンド成功率
• get_ssh_command_stats() — すべてのホストを対象としたコマンドごとの統計
• SSH 専用のインサイト：不安定なホスト、信頼性の高いホスト、失敗するコマンド
• SSH の追跡用テストを 31 件追加

0.3.0

A.L.A.N. 2.0 — 「失敗してるのかもしれないし、うまくやってるのかもしれない」

• リトライ検出：失敗したコマンドを繰り返すと警告します
• 連続記録：成功を称え、失敗時に警告します
• あいまいなテンプレート照合：類似するコマンドをグループ化します
• プロアクティブなインサイト：実行前に状況に応じたフィードバックを提供します
• セッションメモリ：15 分間のローリングウィンドウ
• 新しいデータベーステーブル：recent_commands、streaks

0.2.0

• ライブ監視を備えた yield ベースの実行
• 完全なターミナルエミュレーションのための PTY モード
• zsh_send による対話形式の入力サポート
• タスク管理：zsh_poll、zsh_kill、zsh_tasks
• subprocess.PIPE を使用して stdin のブロッキングを修正

0.1.0

• 初回リリース
• NEVERHANG サーキットブレーカー
• A.L.A.N. 学習データベース

---

ライセンス

MIT ライセンス - 詳細は LICENSE をご覧ください。

---

Johnny5のために。私たちのために。
ArkTechNWA