pi-coding-agent Extension 設計リファレンス

スクリプトやアドホックなCLI実行を卒業し、再利用可能な TypeScript Extension としてオーケストレーション機能をカプセル化する設計ガイドです。

1. Extension の配置場所とスコープ

配置パス	スコープ	用途
~/.pi/agent/extensions/*.ts	グローバル	どのディレクトリで pi を立ち上げても常に使える共通機能・ツール。
.pi/extensions/*.ts	プロジェクトローカル	該当プロジェクト（リポジトリ）固有のデータ処理やワーカ起動ルール。Git管理可能。
pi -e ./path.ts	実行時指定	開発中の Extension のテスト・検証。

2. Extension で公開すべきコンポーネント

• カスタムツール (pi.registerTool): LLMが直接呼べるネイティブツール（例: herdr_spawn_worker, herdr_prompt_worker）。 これを用意することで、LLMが自前で長い bash コマンドや jq を組み立てる必要がなくなり、決定論的かつ高速・安全に動作します。
• スラッシュコマンド (pi.registerCommand): 人間がTUI上で手動実行するショートカット（例: /herdr-status）。
• ライフサイクルイベント (pi.on): セッション開始時に herdr のヘルスチェックを行ったり、危険なコマンドの実行をフックして遮断。

3. 堅牢な Extension 設計のベストプラクティス

1. 型定義の強制: typebox を使って引数スキーマを厳密に定義し、LLMのパラメータ誤認を防ぐ。
2. 標準出力とJSONの二重化パース: herdr の出力が JSON の場合とプレーンテキストの場合の両方にフォールバック対応する。
3. タイムアウト制御: ワーカエージェントの暴走やブロックに備え、デフォルトタイムアウト（180秒など）を設ける。