Zsh Tool

🚀 zsh-tool

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

🚀 クイックスタート

Claude Codeを使用している際に、zshを使うとBashツールでは引用符の不一致やシェルの混乱が発生することがあります。zsh-toolはこの問題を即座かつ恒久的に解消します。

✨ 主な機能

Yieldベースの実行

コマンドはyield_after秒後に、まだ実行中であれば部分的な出力とともに戻ります。

• ハングの解消 — 常に制御を取り戻せます。
• インクリメンタルな出力 — zsh_pollで収集できます。
• インタラクティブな入力 — zsh_sendで送信できます。
• タスク管理 — zsh_killとzsh_tasksで管理できます。

PTYモード

インタラクティブなプログラム用の完全な疑似端末エミュレーションです。

# pty: trueで有効化
zsh(command="pass insert mypass", pty=true)
# プロンプトを表示し、zsh_sendで入力を送信します

• インタラクティブなプロンプトの適切な処理
• TTYを必要とするプログラム
• カラー出力とターミナルエスケープシーケンス
• 完全なstdin/stdout/stderrのマージ

NEVERHANGサーキットブレーカー

ハングするコマンドがセッションをブロックするのを防ぎます。

• コマンドハッシュごとのタイムアウトパターンを追跡します。
• 1時間のローリングウィンドウ内で3回のタイムアウト後にサーキットを開きます。
• 5分後に自動回復します。
• 状態: CLOSED (通常) → OPEN (ブロッキング) → HALF_OPEN (テスト)

A.L.A.N. 2.0 (As Long As Necessary)

インテリジェントな短期学習機能です。

• リトライ検出 — 失敗したコマンドを繰り返し実行すると警告します。
• 連続成功/失敗の追跡 — 成功ストリークを祝い、失敗ストリークで警告します。
• ファジーマッチング — git push origin feature-1 → git push origin *
• プロアクティブな洞察 — コマンドを実行する前にコンテキストに応じたフィードバックを提供します。
• セッションメモリ — 15分のローリングウィンドウで最近のアクティビティを追跡します。
• 時間的減衰 — 指数関数的な減衰 (24時間の半減期) で自動的に削除します。
• SSHインテリジェンス — ホストの接続性とリモートコマンドの成功を分けて追跡します。
• パイプラインセグメントの追跡 — cat foo | grep -badopts | sortが失敗した場合、A.L.A.N.はどのセグメントが失敗したかを知ります。

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

zsh_pollは返る前に2秒間のリスンウィンドウを実行します。2秒以内に出力が到着した場合、すぐに返ります。そうでない場合、ポーリングメタデータがエージェントに何が起こっているかを伝えます。

提案は参考程度で、エージェントが常に判断します。2分間のpip installが40回の空の往復を生成しなくなります。

キル対応型A.L.A.N.

エージェントがコマンドをキルすると、A.L.A.N.はそれをKILLED結果として記録し、なぜキルされたかを分類します。

キルの分類はkill_elapsed / median_durationを比較して、焦りと本当のハングを区別します。

manopt — 失敗時のマニュアルページオプション

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

• 1回目の失敗 — 通常のフィードバック、manoptなし
• 2回目の失敗 — バックグラウンドで非同期のmanopt検索をトリガーします (2秒のタイムアウト)
• 3回目以降の失敗 — A.L.A.N.の洞察にキャッシュされたオプションテーブルを表示します。

ローカルのマニュアルページから解析され、SQLiteにキャッシュされます。デフォルトで有効 (ALAN_MANOPT_ENABLED=1) です。

SSH追跡

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

終了コードの分類:

• 0 — 成功 (接続成功 AND コマンド成功)
• 255 — 接続失敗 (SSHが接続できなかった)
• 1-254 — コマンド失敗 (接続成功だがリモートコマンドが失敗した)

これにより、ssh host3 'git pull'が終了コード255で失敗した場合、A.L.A.N.はホストが到達不能であることを知ります — git pullが壊れているわけではありません。

📦 インストール

マーケットプレイスからのインストール (推奨)

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がインストールされている必要があります。

💻 使用例

基本的な使用法

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

📚 ドキュメント

ツール

アーキテクチャ

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
│           ├── 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 — デフォルトのタイムアウト (120秒)
• NEVERHANG_TIMEOUT_MAX — 最大タイムアウト (600秒)
• ALAN_MANOPT_ENABLED — 失敗時にマニュアルページのオプションヒントを有効にする (デフォルト: 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.6.1

プロトコル修正 — Claude Code v2.1以降のベアJSON-RPCサポート

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

0.6.0

完全なRustリライト — Pythonを廃止し、高速化を実現

• Rustで完全に書き直されました — MCPサーバー、エグゼキューター、A.L.A.N.、NEVERHANG、すべてネイティブ。
• 79のRustテスト — ユニットテスト + 完全なMCP統合テスト (JSON-RPCの往復)。
• CIパイプラインの書き直し — cargo test + cargo clippyがpytest + ruffに代わりました。
• Pythonの削除 — 7,600行以上のPythonコードが削除され、Pythonの依存関係がゼロになりました。
• 約2倍高速なCI — コールドビルドが97秒からキャッシュ済みの48秒に短縮 (Pythonの60 - 120秒と比較)。
• すべての機能が保持されています: yield/ポーリング/送信/キル、PTYモード、A.L.A.N. 2.0、NEVERHANG、manopt、SSH追跡、パイプラインセグメント。

0.5.0

A.L.A.N. v2アップグレード — インテリジェントなポーリング、キル対応、manopt

• インテリジェントなポーリング: zsh_pollの2秒間のリスンウィンドウで空の往復を削減します。ポーリングメタデータには時間予測と適応的な提案が含まれます。
• キル対応型A.L.A.N.: KILLED結果タイプと経過時間の追跡。早期キル (焦り)、遅いキル (本当のハング)、およびパターン問題 (間違ったアプローチ) を分類します。
• manopt統合: 繰り返しコマンドが失敗した場合の非同期マニュアルページオプション解析。SQLiteにキャッシュされ、同じコマンドテンプレートの3回目以降の失敗で表示されます。
• 新しいoutcome_typeとkill_elapsed_ms列が観測値に追加されました。
• 永続的なマニュアルページオプションの保存用の新しいmanopt_cacheテーブル。
• 環境変数: ALAN_MANOPT_ENABLED、ALAN_MANOPT_TIMEOUT、ALAN_MANOPT_FAIL_TRIGGER、ALAN_MANOPT_FAIL_PRESENT。

0.4.90

フィードバックの改善 — シグナルを向上させ、ノイズを減らす

• ALANの洞察が情報/警告のタプルとして分類されるようになりました。
• コマンドの認識: grepの終了コード1 = "一致なし" (情報)、終了コード127 = "コマンドが見つからない" (警告)。
• 実行後の洞察: サイレント検出、パイプマスキング警告、SIGPIPE除外。
• メタデータ行のANSIカラーリング (緑=成功、赤=失敗、シアン=実行中、黄色=タイムアウト)。
• 終了コードに基づくCOMPLETED/FAILEDステータスワード。
• 生のpipestatusリストがフォーマットされた[cmd:code]文字列に置き換えられました。
• グループ化された洞察表示: [info: A.L.A.N.: ...]と[warning: A.L.A.N.: ...]。

0.4.83

Python 3.14サポート — 将来対応

• Python 3.14のクラシファイアとバッジが追加されました。
• 非推奨のasyncio.DefaultEventLoopPolicyフィクスチャが削除されました (3.16で削除予定)。
• すべての331のテストがPython 3.14.2で通過します。

0.4.81

Pipestatusマーカーのリーク修正 — データの整合性

• ___ZSH_PIPESTATUS_MARKER___が出力に漏れる競合状態が修正されました。
• マーカーは_build_task_response()で呼び出し元に返す前に削除されます。
• 実行中に出力がキャプチャされた場合のファイル内容の破損を防ぎます。
• CI: ランナーがdockerエグゼキューターに切り替えられ、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%のカバレッジ

• ユーザー設定ファイル (~/.config/zsh-tool/config.yaml) でカスタムのyield_afterを設定できます。
• テストカバレッジが向上: 303のテスト、91%のカバレッジ。
• タスククリーンアップのヌルチェックバグが修正されました。
• ロゴファイルが統合され、修正されました。

0.4.5

バンドルされたプラグイン — 摩擦のないマーケットプレイスインストール

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

0.4.0

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

• すべてのモジュールをカバーする包括的なテストスイート。
• テストとリントステージを持つCIパイプライン。
• 動的なパイプラインとカバレッジバッジ。
• 優しいテストランナー (run_tests.sh) でファイル間にniceとsleepを入れます。
• 非推奨の警告とリントエラーが修正されました。
• 非同期テストサポートのためにpytest-asyncioが追加されました。

0.3.1

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

• SSHコマンドが2つの観測値 (ホスト + リモートコマンド) を記録するようになりました。
• 終了コードの分類: 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