pi エージェントツールキット: 5 つのパッケージ、SDK レシピ、判定表、月曜のチェックリスト

TL;DR

• pi は MIT ライセンスのモノレポで、コーディングエージェントのハーネスを 5 つの独立したパッケージとして提供します。モデル API レイヤー、エージェントループ、ターミナル UI ライブラリ、コーディングエージェント本体、テレメトリです。1 つだけ使うことも、5 つすべて使うこともできます。
• CLI は初日から完成したコーディングエージェントです。デフォルトツールは 4 つ、フォークと再開ができるツリー型のセッション履歴、リアルタイムのコストカウンター、そしてリポジトリにすでにある AGENTS.md や CLAUDE.md を読み込みます。
• 本当の価値は SDK 側にあります。createAgentSession にモデルランタイムとセッションマネージャーを渡すだけで、約 10 行の TypeScript で動くエージェントになり、defineTool を使えば別プロセスもプロトコルも使わずに型付きのカスタムツールを追加できます。
• この透明性の代償は手間です。権限確認の仕組みは組み込まれておらず、隔離は自分で用意する必要があり、バージョンは 1.0 前(v0.84)で、オープンな issue は約 100 件あります。
• 普段使いのハーネスはそのまま使い、pi はそのハーネスが隠しているものを見せてくれる検証用の環境として使いましょう。ガードレールを自分で持つ覚悟がある場合にだけ、pi の上にプロダクトを作ってください。

ソースが伝えていること

pi はモノレポです。1 つのリポジトリに、別々に公開される 5 つのパッケージが入っていて、それぞれがハーネスの 1 層を担当します s2。pi-ai はモデルプロバイダー(OpenAI、Anthropic、Google など)への統一 API で、1 つのインターフェースの裏でレスポンスのストリーミング、thinking レベル付きの reasoning ブロック、各プロバイダーが提供するモデルの動的な検出を扱います s2。pi-agent-core はエージェントループそのものです。会話の状態と、メッセージを送り、ツール呼び出しを読み、実行し、結果を返すサイクルを持ちます s2。pi-tui は差分レンダリングを備えたターミナル描画ライブラリで、画面上で変わった部分だけを再描画します s2。pi-coding-agent はこれらの部品を組み合わせて、インストールする CLI にしたものです。pi-telemetry を使うと、特定のベンダーに依存せずに自分の使用量メトリクスを接続できます s3。

採用状況の数字も設計を裏付けています。92 123 のスター、11 400 のフォーク、5 700 を超えるコミットで、すべて MIT ライセンスのもとにあり、商用プロダクトへの組み込みを含めて利用、改変、再配布が可能です s1。リリースの頻度は夏の間も維持されました。8 月の最初の 2 週間に 3 回のリリースがあり、v0.84.2 は 14 日に公開されました s4。

インストールはコマンド 1 つ、npm install -g --ignore-scripts @earendil-works/pi-coding-agent です。ignore-scripts フラグには意味があります。依存パッケージのインストールスクリプトの実行を止めるもので、これは npm で最もよく使われる攻撃経路の 1 つです s3。login コマンドでプロバイダーに接続すると、下部のバーに現在のフォルダー、セッション、消費トークン、そしてリアルタイムのコストが表示されます。リクエストは月末ではなく、送信するたびに料金が分かります s3。

セッションは pi の特徴的な機能です。すべての会話はホームフォルダーにプロジェクトごとに JSONL として保存され、履歴は直線ではなくツリーになっています。fork は任意の地点に戻って分岐し、tree はブランチ間を移動し、resume は過去のセッションを何週間後でも開き直せます。すべてローカルに保存されているからです s3。モデルがデフォルトで受け取るツールは 4 つだけです。read、write、edit、bash で、市場にある他のエージェントと比べてとても少なく、それは意図的です s3。設定も同じ考え方です。ホームにグローバルな settings.json があり、プロジェクトごとの settings.json がそれを上書きし、初めて開くフォルダーのローカル設定を適用する前には確認を求める trust の仕組みがあります。CLI はプロジェクトの AGENTS.md や CLAUDE.md もコンテキストとして読み込むので、既存の指示を書き直さずにそのまま使えます s3。

SDK 側では、createAgentSession が ModelRuntime と SessionManager を受け取り、動作するエージェントを返します。SessionManager は永続化の選択肢です。使い捨てスクリプトならメモリ上、起動をまたいで会話を見つけ直したいならディスク上に置きます。SDK が作るセッションは CLI 自身のセッションと同じ構造を持ちます s8。createAgentSession のオプション一覧では、公開するツールの集合を正確に選べますし、白紙から始めたい場合は ResourceLoader を通じてシステムプロンプト全体も選べます s8。カスタムツールは defineTool を通します。名前、説明、型付きのパラメータスキーマ、execute 関数を指定し、customTools として createAgentSession に渡します。モデルから見ると、そのツールは read や bash とまったく同じように見えます。型付きスキーマのおかげでエディターの補完が効き、エージェントは検証済みの入力を受け取ります。これは MCP サーバーと同じ仕組みですが、すべてが自分のファイルの中にあり、別プロセスも間に挟まるプロトコルもありません s8。

CLI 自体は 4 つの仕組みでカスタマイズします。いずれもプロジェクトまたはホームのフォルダーに置きます。extensions(ツール、スラッシュコマンド、キーボードショートカット、UI 要素を登録する TypeScript モジュールで、起動時に extensions フォルダーから読み込まれます)、skills(Agent Skills 標準に従った機能パッケージで、モデルが呼び出すことも手動で呼び出すこともでき、既存の skills をそのまま再利用できます)、prompt templates、そして CLI の実行中にリロードされる themes です s3。README は思想を 1 行で述べています。pi を自分のワークフローに合わせるのであって、その逆ではなく、フォークも内部への手入れも要らない、というものです s3。大きなハーネスがサブエージェント、plan mode、権限管理を製品に同梱するのに対し、pi は意図的にそれらを外していて、extensions として自分で書くか、コミュニティのものをインストールします s3。

制限はプロジェクト自身が文書化しています。権限確認の仕組みは組み込まれていません。デフォルトでは、エージェントは確認なしで bash コマンドを実行できます。公式のコンテナ化ガイドはこれを認めたうえで、Docker を含む 3 つの隔離パターンを提案していますが、大事なマシンでエージェントを動かす前にそれを用意するのは自分の仕事です s5。成熟度がもう 1 つのコストです。1.0 ではなく v0.84 で、オープンな issue は約 100 件あり、ここ数週間で追加された remote session client のように experimental と記された API もあります s7。同じ部品はすでに別のプロダクトにも使われています。pi-chat はそれらを会話の自動化に応用しています s6。

判定: 残す、試す、見送る

月曜にやること

• npm install -g --ignore-scripts @earendil-works/pi-coding-agent で CLI をインストールし、pi を実行し、login コマンドでプロバイダーに接続して、実際のタスク 1 つの間コストバーを観察する。
• すでに AGENTS.md や CLAUDE.md があるリポジトリを開き、pi がそれを読み込むか確認する。同じプロンプトで、エージェントの最初の回答をいつものハーネスと比べる。
• 会話を 1 つ実行し、前のノードから fork して別の方向に進める。~/.pi/agent/sessions/ を一覧して JSONL ファイルとプロジェクトフォルダーを確認する。
• 20 行の our-agent.ts を書く。createAgentSession を import し、ModelRuntime とメモリ上の SessionManager を渡し、現在のフォルダーの中身を尋ねて、npx tsx で実行する。
• 自分のシステム(社内 API、データベースのビュー、CSV)から何かを読む defineTool を 1 つ追加して customTools に渡し、関連する質問でエージェントが促されなくても呼び出すことを確認する。
• 大事なマシンで bash を有効にして実行する前に、コンテナ化ガイドの 3 つの隔離パターンから 1 つを選んで用意する。
• 破壊的なコマンドで確認を求めるように bash 呼び出しを横取りする最初の extension を下書きし、プロジェクトの extensions フォルダーでバージョン管理しておく。
• オープンな issue の一覧に一度目を通し、土台にする前にどの部分が動いているかを把握する。

さらに読む

• createAgentSession のオプション一覧の全体(ツールセット、ResourceLoader 経由のシステムプロンプト、セッションマネージャー)は SDK ドキュメントで確認する s8。
• ユーザーのマシンで bash を実行するものを出荷する前に、コンテナ化ガイドの 3 つの隔離パターンを調べる s5。
• pi-chat を見て、同じ 5 つのパッケージがコーディングではなく会話の自動化向けにどう組み替えられているかを確認する s6。
• packages フォルダーを眺め、pi-agent-core を単独で読む。同梱型ハーネスがすべて回しているループの、最も小さく読みやすい版です s2。
• リリースページを追う。v0.84.0 から v0.84.2 までは 8 月の 2 週間以内に出たので、extensions に影響する変更ノートが出ると考えておく s4。
• オープンな issue を、まだ experimental な部分の地図として使う。まず remote session client から s7。
• 他のツール向けにすでに書いた skills を再利用する。pi の skills フォルダーは Agent Skills 標準に従っています s3。

ソース

• pi: the agent toolkit (repository), Earendil Works. 読む理由: パッケージ一覧、スターとフォークの数、MIT ライセンスが載った README。
• pi monorepo packages, Earendil Works. 読む理由: 5 つのパッケージが並んでいて、各層をどれが担当しているかを最も早く把握できる。
• pi-coding-agent package README, Earendil Works. 読む理由: インストールコマンド、デフォルトツール、セッション、4 つの拡張の仕組み。
• pi releases, Earendil Works. 読む理由: v0.84 系列のリリース頻度と変更履歴。
• pi containerization guide (isolation patterns), Earendil Works. 読む理由: 大事な環境で bash を有効にする前に適用すべき 3 つの隔離パターン。
• pi-chat: the same bricks applied to conversation automation, Earendil Works. 読む理由: 同じパッケージから作られた 2 つ目のプロダクトで、再利用のしやすさを判断するのに役立つ。
• pi open issues, Earendil Works. 読む理由: 現行バージョンで不安定または experimental な部分の最新リスト。
• pi-coding-agent SDK documentation (createAgentSession options), Earendil Works. 読む理由: createAgentSession、defineTool、セッションマネージャーの正確なオプション名。

FAQ

今日の pi は、普段使っているコーディングエージェントの代わりになりますか?

そのまま置き換えることはできません。権限確認の仕組みがなく、隔離は自分で用意する必要があり、バージョンは 1.0 前でオープンな issue が約 100 件あります。仕事には今のハーネスを使い続け、pi は隣で動かしてください。

pi にカスタムツールを追加するのに MCP は必要ですか?

いいえ。defineTool は名前、説明、型付きのパラメータスキーマ、execute 関数を受け取り、ツールは customTools として createAgentSession に渡されます。組み込みツールと同じように動作し、別プロセスもプロトコルも要りません。

既存の AGENTS.md、CLAUDE.md、skills は使えますか?

はい。CLI はプロジェクトの AGENTS.md や CLAUDE.md を自動で読み込み、skills フォルダーは Agent Skills 標準に従っているので、既存の skills はそのまま読み込まれます。

なぜデフォルトのツールは 4 つだけなのですか?

read、write、edit、bash がデフォルトのすべてで、市場にあるエージェントよりずっと少なく、プロジェクトはそれを意図した選択だと説明しています。ほかに必要なものは、customTools や extension を通して意図的に追加します。