wezterm-ai-agents: Instructions file for Claude Code

CLAUDE.md

概要

WezTerm プラグイン。並列 AI コーディングエージェントセッションを管理する。WezTerm の Lua 5.4 サンドボックス上で動作する (テスト/lint は LuaJIT で実行)。永続ワークスペース、git worktree 連携、タブ/ペイン UI によるエージェント状態追跡を提供。

コマンド

# Lint
luacheck .

# フォーマットチェック
stylua --check .

# フォーマット修正
stylua .

# 全テスト実行 (luajit 必須)
bash test/run.sh

# 単体テスト実行
luajit test/test_agent.lua

アーキテクチャ

plugin/init.lua がエントリポイント。dofile() で全モジュールをロードする。WezTerm サンドボックスは wezterm / mux グローバルを提供するが、debug ライブラリは使用不可。

ディレクトリ構成（レイヤ別。init.lua がロード順=依存階層で全体を接続）:

plugin/
├── init.lua            — エントリポイント、apply() で層順にロード+結線
├── ui/                 — 上位層: 描画・操作
│   ├── ui.lua          — タブタイトル、右ステータスバーの描画
│   └── selector/       — InputSelector ベースの UI + キーバインド
│       ├── init.lua    — coordinator (build_keybinds / agent選択 / pin)
│       ├── workspace.lua — ワークスペース選択/登録/削除 UI
│       ├── worktree.lua  — worktree/PR/Issue 選択 UI + prefetch
│       └── ui.lua      — フォーマット共通ヘルパー (setup で両UIに注入)
├── state/              — 中位層: 永続化・配置 (循環は agent_mod/layout_mod 注入で回避)
│   ├── workspace/
│   │   ├── init.lua    — JSON永続化 + CRUD
│   │   └── session.lua — タブ状態のスナップショット/同期/ワークスペース生成
│   └── layout.lua      — ペイン分割レイアウトのスナップショット/復元
├── service/            — 下位層: 外部I/O・検出 (UI に依存しない)
│   ├── agent.lua       — エージェントレジストリ、検出、状態集約、JSON リーダー
│   ├── agents/         — 各エージェント実装 (claude/codex/cursor/gemini)
│   ├── worktree/
│   │   ├── init.lua    — ローカル git worktree 操作 (list/add/remove/prune) + 命名/パス展開
│   │   └── github.lua  — PR/Issue 連携 (gh 取得・キャッシュ・パース・フィルタ・worktree生成)
│   ├── editor.lua      — エディタ検出・起動引数
│   └── links.lua       — ターミナル出力パスの editor:// リンク化
└── resource/           — 下位層: 静的データ
    ├── labels.lua      — i18n ラベル (en/ja)
    └── icons.lua       — アイコンセット (unicode / nerd)、opts.nerd_font で切替

主要パターン:

• エージェント状態は hooks が pane ごとに JSON ファイルを書き込む push 方式: $XDG_STATE_HOME/wezterm-ai-agents/<gui_pid>/wezterm-agent-<pane_id> (GUI プロセス PID 名前空間配下。フォールバック ~/.local/state)
• hooks/agent_status.sh が書き込み側 (全エージェント共通)。Lua 側は wezterm.json_parse() で読み取り
• PID 名前空間は書き込み側 WEZTERM_UNIX_SOCKET の gui-sock-<pid> と読み取り側 wezterm.procinfo.pid() が同一 GUI プロセス PID に合意する前提 (mux 内蔵の既定構成のみ。分離 mux 構成は非対応)
• JSON 形式: {"agent":"<id>","state":"<state>","ts":<unix>,"session_id":"<sid>"}
• ワークスペースデータは $XDG_STATE_HOME/wezterm-ai-agents/workspaces.json (PID 名前空間なし) にアトミック書き込み (tmp + rename)
• 循環依存は関数引数でモジュールを渡して回避 (agent_mod, layout_mod)
• 非同期/外部コマンド実行の方針は docs/async.md を参照 (UI ブロック回避、背景取得 + キャッシュ等)