piの中身、9.2万スター獲得ツールで自分のエージェントを作る

Claude Code、Codex、Gemini CLIは、誰か他人が設計したエージェントハーネスだ。そしてその1つの中で働く日々を過ごすなら、あなたはその設計判断とともに生きることになる。挙動を変えたい、ツールを足したい、権限ルールを絞りたい。それでもベンダーが出す気になるのを待つしかない。システムプロンプトの中身は分からず、ツールを回すループも見えず、その何一つとして変えられない。それでもこれらのツールは、すでに何千人もの開発者の主戦場になっている。

1つのオープンソースプロジェクトが、まったく逆の道を選んだ。pi、モデルコネクタからインターフェースまで、自分だけのエージェントを組み立てる部品を提供するツールキットだ。最初の1年でGitHubスター9万2000を獲得し、ほぼ毎週リリースを出している。この記事では、piが実際に何を提供するのか、そのSDKで自分のエージェントをどう作るか、そして既製ハーネスに対する正直な評価を扱う。

ハーネスとは、言語モデルを動くエージェントに変える、その周りのすべての仕組みのことだ。モデル単体にできることは1つだけ。テキストを読み、テキストを出す。ファイルは読まず、コマンドも一切実行せず、セッションが変わると何も覚えていない。それ以外の仕事はすべてハーネスが担う。モデルを枠づけるシステムプロンプト、モデルに与えるツール、ツール呼び出しを実行し結果を返すループ、そしてターミナルのインターフェース。

ハーネスは日々の違いを生む細部も決めている。コンテキストが溢れたとき履歴をどう圧縮するか、ツールのエラーがどうモデルに戻るか、何をログするか。Claude Codeはハーネスだ。Codexも同じ。あるエージェントに感心したなら、その手柄の多くはモデルでなくこの機構のものだ。同じモデルを2つの違うハーネスに載せれば、まるでレベルの違う2つのエージェントが生まれる。

Earendil Worksが作ったpiは、その機構を再利用可能なブロックに分解した。コーディングエージェントをそのまま使うこともできるし、ブロックを1つずつ取って自分で組むこともできる。我々が気になるのは後者の方だ。

piはモノレポ、つまり1つのリポジトリに個別に公開された5つのパッケージが入っている。各パッケージがハーネスの1階層を担う。

パッケージ	役割
pi-ai	OpenAI、Anthropic、Google他への統一API。レスポンスのストリーミング、思考レベル付きの推論ブロック、各プロバイダのモデルの動的検出まで扱う。ラボの切り替えは引数を変えるだけ。
pi-agent-core	エージェントループそのもの。会話の状態、メッセージ送信、ツール呼び出しの読み取り、実行、タスク完了までの結果返却というサイクル。失敗するツール、途中で切れるレスポンス、並行して届く呼び出しといったややこしいケースは既に対処済み。
pi-tui	差分レンダリングを使うターミナル描画ライブラリ。画面上の変化した部分だけを再描画する。
pi-coding-agent	上記のブロックから組まれた完全なコーディングエージェント。ツールキットだけで完成品が作れる証拠だ。
pi-telemetry	ベンダーに依存せず自分の利用メトリクスを組み込める。

エージェントループは、まさにゼロから書くと下手になりがちな部分だ。それをきちんと書くのは数週間の作業だが、それをimport1つで手に入れる。チームは同じレシピを他でも使っている。別のリポジトリpi-chatは、同じブロックを会話の自動化に再利用する。

数字がこの公式の正しさを示している。

指標	値
GitHubスター	92,123
フォーク	11,400
コミット	5,700以上
ライセンス	MIT
2026年8月最初の2週間のリリース数	3(v0.84.2は8月14日)

MITライセンスということは、商用製品を含め、制限なく使い、改変し、再配布できるということだ。piは単なるフレームワークの1つではない。部品化された完全なハーネスであり、着実なペースで保守されている。

piのCLIは、コードに一切触れる前に手に入る、組み立て済みのコーディングエージェントだ。ここから始めることになる。インストールは1行だが、--ignore-scriptsフラグは軽視できない。依存パッケージにインストールスクリプトを実行させないためのもので、npmで最も悪用される攻撃面の1つだ。piを起動し、loginコマンドでプロバイダを接続すれば、ターミナルの中にコーディングエージェントができる。ステータスバーには現在のフォルダ、セッション、消費トークン、そしてリアルタイムのコストが表示される。月末に請求額を知る代わりに、リクエストが出た瞬間に価格が見える。

スラッシュコマンドが日常をカバーする。modelでモデル切替、compactでコンテキストが膨らんだ履歴を要約、exportで会話を取り出し、残りはsettings。promptsフォルダのmarkdownファイル1つが、名前を打つだけで実行できるコマンドになる。

piの真骨頂はセッション管理にある。各会話はプロジェクトごとにホームフォルダにJSONLとして保存される。そして履歴は実は線でなく、ツリー構造だ。会話のどの地点にも戻ることができ、forkコマンドで別の道に進める。そしてtreeでブランチ間を移動する。失敗したプロンプトはもう何も損しない。前のノードに戻ってやり直せば、別のブランチを失わずに済む。すべてローカルに保存されるので、resumeなら何週間後でも過去のどのセッションにも戻れる。Claude CodeもCodexも、この形式の履歴ナビゲーションは提供していない。

デフォルトでは、モデルは4つのツールしか持たない。read、write、edit、bash。市場のエージェントに比べてかなり少ないが、それは意図的なものだ(後で触れる)。設定も同じロジックに従う。ホームフォルダのグローバルな設定ファイル、それを上書きするプロジェクトごとの設定、そして初めて開くフォルダのローカル設定を適用する前に確認するtrustシステム。移行する場合、piは既存のAGENTS.mdやCLAUDE.mdを自動でコンテキストに読み込むので、既存の指示は書き直さず動く。

piのSDKでエージェントを作るのは、1つのimportから始まる。createAgentSessionにモデルランタイムとセッションマネージャを渡せば、動くエージェントが返ってくる。セッションマネージャは永続化の選択肢だ。使い捨てスクリプトならメモリ、実行ごとに会話を見つけたいならディスクに保存する。

ローカルプロジェクトで試してみた。スクリプトが現在のフォルダの中身を聞くと、エージェントがreadツールを呼び、フォルダを読んで答える。それが完全なループで、我々が書き、TypeScript約10行で済んだ。SDKが作るセッションもCLIと同じツリー構造を持ち、各メッセージは親に紐づく。だから履歴の分岐は自分のコードの中でも機能する。

面白くなるのはカスタムツールからだ。defineToolは名前、説明、型付きパラメータスキーマ、execute関数を受け取り、そのツールはreadやbashと全く同じようにモデルに現れる。チャンネルの動画一覧を照会するツールを書き、customToolsに渡すと、最初に関連する質問が来た時点でエージェントが自分から呼んだ。これは基本的にMCPサーバーと同じ仕組みだが、すべてがあなたのファイル内に住み、別プロセスもプロトコルも間に挟まらない。パラメータスキーマが型付きなので、エディタが引数を自動補完し、エージェントは検証済みの入力を受け取る。

モデルの制御もできる。完全オフから最大までの思考レベル、モデルに見せるツールの正確な一覧、そして白紙から始めたいならリソースローダー経由でシステムプロンプト全体さえも。表示のためには、session.subscribeがあらゆるイベント(ストリーミングテキスト、ツール呼び出し、エラー)を渡してくれる。それを好きな場所に流せる。ターミナル、メッセージングボット、あるいはプルリクエストにコメントするCIパイプラインへも。つまり午後の間に、エージェントを使う側から書く側になり、ループの各ターンで何が起きているかようやく分かるようになる。

piのCLIは4つの仕組みでカスタマイズできる。すべてプロジェクトかホームの普通のフォルダに置かれる。

• Extensions — ツールやスラッシュコマンド、キーボードショートカット、UI要素を登録するTypeScriptモジュール。extensionsフォルダにファイルを置けば起動時に読み込まれる。たとえば権限ガードを書く場所はここだ。bashコマンドを傍受し、危険なものの前に確認を求める拡張機能。
• Skills — Agent Skills標準に従う能力パッケージ。Anthropicが広めたのと同じ標準なので、既存のskillsはそのまま再利用できる。
• Prompts — 再利用可能なプロンプトを、ただのmarkdownファイルとして。
• Themes — CLI実行中にホットリロードされる。

すべて普通のパッケージのようにインストールできる。pi installはnpmパッケージやGitリポジトリを取り、1コマンドで全体を更新する。ドキュメントはその哲学を1文にまとめている。フォークも内部パッチも不要で、piをあなたのワークフローに合わせる、その逆ではない。

これは大手ハーネスの真逆だ。Claude Codeがサブエージェント、プランモード、権限を製品内に搭載する一方、piは意図的にそれらを外に置く。拡張機能として作るか、コミュニティからインストールする形で。狙いは明確だ。ほとんど動かない最小限のコアと、あなた側に住むすべてのカスタマイズ。プロジェクトと一緒にバージョン管理するファイル群として。

piの透明性は作業量で支払われる。その代償は3つある。

まずガードレール。デフォルトでは組み込みの権限確認がなく、エージェントは何も聞かずにbashコマンドを実行できる。公式ドキュメントはそれを認め、Docker込みで3つの分離パターンを提案しているが、重要なマシンでエージェントを解き放つ前にそれを整えるのは、あなた自身の仕事だ。

次に成熟度。これはv0.84で、1.0ではない。約100件のオープンイシューと、いくつかの実験的なAPI(最近追加されたリモートセッションクライアントなど)がある。今日動くものが次のリリースで壊れることもあり、これほど速く進むプロジェクトの当然の代償だ。

そして最後に時間。Claude Codeが標準で与えてくれる快適さ(プランモード、サブエージェント、細かい権限)は、ここでは自分で作るプロジェクトになるか、維持され続けることを願って追いかけるコミュニティパッケージになる。拡張機能エコシステムはまだ1年で、既製パッケージより埋めるべき穴の方が多く見つかるはずだ。インストール自体が、--ignore-scriptsフラグを通じて必要な警戒レベルを教えてくれる。そのレベルを鎖全体で保つ必要がある。今夜コードを出荷するのが目標なら、piは加速する前にまず減速させる。この動画だけを理由に今週メインハーネスを変えないでほしい。

piは、1つのエージェントではなく複数のエージェントで製品を作る開発者のためのものだ。彼らにとって、これは今のところ最良の学習投資かもしれない。CLIを入れ、SDKで20行のエージェントを書き、自分のツールを1つ与えてみよう。それをやれば、ほとんどのユーザーよりClaude Codeを理解できるようになる。

今日ただ生産的なアシスタントが欲しいなら、統合ハーネスを使い続け、1.0がガードレールを備えたら戻ってこよう。piの価値は理解と制御にあり、即座の快適さにはない。そして両者の間には、リスクなしの中間地点がある。仕事にはClaude Codeを使い続け、piをメインツールが隠しているものを知るための試験台にすればいい。

一番の学びは、ハーネスがもうブラックボックスではないということだ。部品はテーブルの上にあり、文書化され、MITライセンスだ。次にエージェントが感心させたり苛立たせたりしたときは、どの部品を見ればいいか正確に分かるようになる。