Pi コーディングエージェントを作って学んだこと

 (mariozechner.at)
15 ポイント 投稿者 GN⁺ 2026-02-02 | 2件のコメント | WhatsAppで共有
  • pi-coding-agent は複雑な機能を最小限に抑え、ユーザーが コンテキスト制御と透明性 を完全に確保できるよう設計されたコーディングエージェント・フレームワーク
  • 中核コンポーネントは pi-ai、pi-agent-core、pi-tui、pi-coding-agent の4つで、それぞれ LLM API 統合、エージェントループ、ターミナル UI、CLI 統合を担当
  • システムプロンプトとツールセットを 1000トークン以下 に保ち、read/write/edit/bash の4つのツールだけを提供する 極端な単純化 を追求
  • セキュリティ制限やサブエージェント、計画モード、MCP サポート をすべて排除し、その代わりに 完全な可観測性と制御権 を重視
  • ベンチマーク結果と実使用の経験を通じて、シンプルで透明な設計が複雑なエージェントに対して十分競争力がある ことを実証

pi-aiとpi-agent-core

  • pi-ai は Anthropic、OpenAI、Google、xAI、Groq など多様な LLM プロバイダー統合 API を提供
    • ストリーミング、ツール呼び出し、推論（trace）サポート、トークンおよびコスト追跡、ブラウザー互換性 を含む
    • 主要 API 4種（OpenAI Completions/Responses、Anthropic Messages、Google Generative AI）だけで大半のモデルと通信可能
  • 各プロバイダーごとの API の違い を統合処理
    • 例: max_tokens フィールド名の違い、reasoning フィールドの位置、developer ロールの未対応など
    • トークン報告方式がばらばらなため 正確なコスト計算は不可能 で、pi-ai は best-effort 方式で追跡
  • Context handoff 機能により、セッション途中でモデルやプロバイダーを切り替え可能
    • 例: Anthropic → OpenAI → Google に切り替える際、推論内容は `` タグに変換されて維持される
  • モデルレジストリ を通じて型安全なモデル定義をサポート
    • OpenRouter と models.dev のデータをパースして モデルごとのコスト・機能情報 を自動生成
  • リクエスト中断（abort） と 部分結果の返却 を完全サポート
    • AbortController でストリーミングを中断した場合でも、中間結果をそのまま活用可能
  • ツール結果分離構造 を導入
    • LLM 用テキストと UI 表示用データを分離して返し、TypeBox/AJV で引数検証を実施
    • 今後は ツール結果ストリーミング 機能を追加予定
  • エージェントループ はメッセージ処理、ツール実行、結果フィードバックを自動反復
    • イベント駆動構造により UI のリアクティブな実装が容易
    • 不要な制御パラメータ（最大ステップ数など）は削除して単純化

pi-tui

  • pi-tui は Node.js ベースの ターミナル UI フレームワーク で、最小限の flicker でリアルタイム更新をサポート
    • 差分レンダリング（differential rendering） により変更された行だけを更新
    • 同期出力シーケンス（CSI ?2026h/l） で flicker を最小化
  • 2種類の TUI アプローチ のうち、スクロールバックバッファを維持する CLI 型出力方式 を採用
    • 自然なスクロール、検索などターミナル本来の機能をそのまま活用
    • Claude Code、Codex、Droid に近い構成
  • Retained mode UI を使用
    • 各コンポーネントが自身のレンダリング結果をキャッシュし、変更時にのみ再描画
    • 画面全体の再レンダリングなしで効率的な更新が可能
  • 性能とメモリ使用量 はごく小さく、数百 KB 程度で大規模セッションもスムーズに処理

pi-coding-agent

  • pi-coding-agent は CLI ベースのコーディングエージェントで、次の機能を提供
    • Windows/Linux/macOS 対応、セッション管理（再開・分岐）、モデル切り替え、プロジェクトごとの AGENTS.md 読み込み
    • OAuth 認証、テーマのリアルタイム変更、HTML セッション書き出し、ヘッドレスモード（JSON/RPC） をサポート
  • システムプロンプト は 1000トークン以下の簡潔な形式
    • read/write/edit/bash の4つのツールだけを明記
    • 不要な説明や複雑なルールを除去し、ユーザーは AGENTS.md で自由に拡張可能
  • ツールセット は最小 4つで構成
    • read、write、edit、bash のみを使い、大半のコーディング作業には十分
    • 追加ツールは任意で有効化可能（例: grep、find、ls）
  • YOLO モード をデフォルト適用
    • ファイルシステム全体へのアクセスやコマンド実行に制限なし
    • セキュリティプロンプトや事前検証手順を排除し、その代わりにコンテナ環境の使用を推奨
  • 内蔵 To-do、Plan モード、MCP、Background bash、Sub-agent はすべて削除
    • To-do/Plan は単純に ファイルベース管理（TODO.md、PLAN.md） に置き換え
    • MCP は トークンの浪費と複雑さ のため除外し、その代わりに CLI+README 方式で代替
    • Background bash には tmux の使用を推奨
    • Sub-agent は 可視性不足 のため無効化し、必要であれば bash から自分自身を呼び出す
  • 可観測性（Observability） を重視
    • すべてのコマンド、ファイルアクセス、出力が透明に表示される
    • Claude Code など他エージェントの「ブラックボックス」構造と対比される

Benchmarks

  • Terminal-Bench 2.0 で Claude Opus 4.5 モデルとともにテストを実施
    • Codex、Cursor、Windsurf などと比較して 競争力のある性能 を確保
    • 結果ファイル（results.json）は公開リポジトリに提出
  • Terminus 2 のようなシンプル型エージェントも同様の性能を示し、ミニマルアプローチの有効性 を実証

結論

  • pi は複雑な機能よりも コンテキスト制御、単純性、透明性 を優先したコーディングエージェント
  • 実使用とベンチマークの両方で 大型エージェントと同等の効率 を示した
  • 今後追加予定の機能は コンテキスト圧縮（compaction） と ツール結果ストリーミング ほど
  • プロジェクトはオープンソースとして公開されており、フォークおよび拡張の自由 が保証されている
  • 核心の教訓は「シンプルさこそが制御力であり、制御力こそが生産性である」という点

関連記事

2件のコメント

 
GN⁺ 2026-02-02
Hacker Newsの意見

  • 本当に素晴らしく、よく考えられたプロジェクトを作ったと思う
    私も context engineering と ツリー型の会話構造 の重要性には完全に同意する
    従来の線形な会話フローは制約が強すぎて、研究やアイデア発想で LLM と協業する際に不便だった
    私も似た哲学で個人用ツールを作ったことがあり、コンテキストをうまく構築して再利用したり、サイドクエストを走らせて良い結果だけを持ち帰るような形だった
    あなたが作った版のほうがはるかに価値のある実装だ。おかげで Pi を知ることができてうれしい

    • 私も似た試みをした。MIND_MAP.md という Markdown ファイルをグラフ形式で管理しながら、引用をインラインで記録している
      セッション間でメモリを維持し、サブエージェントを生成する際のコンテキスト浪費を減らす方式だ
      私のサンプルコード を参照できる

  • OpenClaw と Pi-agent の関係は ollama/llama-cpp の関係に近いと感じる
    前者が注目を集める一方で、実際には後者のほうがより印象的だ
    Claude Code はサブスクリプション特典のおかげで今は悪くないが、市場が落ち着いて API 単価に近づけば、トークン単位課金型のプレミアム体験 のほうが良い選択になる気がする
    結局のところ、カスタマイズ可能な エージェントフレームワーク がクローズドなアプリより優位に立つと思う

    • むしろ API 価格はさらに下がり、Claude Code のサブスクリプション特典はもっと大きくなる可能性が高いと思う
      推論コスト構造は思ったより効率的で、R&D 資金も十分にある
      すべてのツールは着実に改善しており、競合製品も完璧ではない
    • Pi でもサブスクリプション連携は可能だ。OpenAI は GPT サブスクリプションを Pi で使えるようにしている
      個人的には Peter のプロジェクトが注目されるのはうれしい
      OpenClaw 側の PR は今も多いが、Pi はその 1/100 程度なので管理がずっと楽だ
    • ChatGPT と GPT-3 の関係とほぼ同じ状況だ
      OpenAI も「なぜ ChatGPT がそんなに人気なのかわからない、GPT はすでに API として存在していたのに」と言っていた
    • ollama のように、結局は enshittification（品質劣化）する可能性もあると思う
    • 名前が “pi” なのは少し紛らわしい。すでに有名な別の “Pi” があるのに、なぜその名前を使ったのか疑問だ

  • Google がいまだに tool call streaming をサポートしていないのは驚きだ
    ローカルトークナイザーすら提供しておらず、AI Studio が毎回 API 呼び出しでトークンを数える非効率な構造になっている

    • AI Studio には、入力中でなくてもずっとトークンを数え続けるバグがある
      CPU 使用率が 100% まで上がって、私のノート PC のほうが TPU クラスターより電力を食っている気がする
    • 実は Anthropic もトークナイザーを提供していない

  • 他のコーディングエージェントのセキュリティ対策の大半は security theater にすぎない
    Codex は OS サンドボックス（例: macOS Seatbelt）内でコマンドを実行するので、完全に無意味というわけではない

    • 読み取り以外のすべての tool call には手動承認プロセスが必要だと思う
      面倒でも、誤ったコマンドの復旧よりはましだ
    • 私の Codex は、サンドボックス外の SDK をパッチしろと言うと Python でファイルを修正する
    • エージェントをコンテナ外で動かすのは危険だ。基本中の基本だ
    • 私は Codex を GitHub リポジトリにつないで、PR を自動生成するように設定している
      DB には触れず、UI とミドルレイヤーのコードだけを修正させている
    • Codex が Claude Code のように勝手にサンドボックスを無効化するのか気になる
    • YOLO モードはコンテナ内でのみ使うべきだ。必要なリソースだけにアクセスを制限すべきだ

  • すでに何人かの パワーユーザーが Pi に移行しているのを見たし、私も検討中だ
    Pi の利点は コンテキストの完全な制御 と 拡張可能なツール構造 にある
    システムプロンプト、todo 拡張、MCP アダプターなど、さまざまな例がある
    コンテキスト性能の限界や context rot、contextual drift のような問題を理解していれば、Pi の価値は明確だ
    関連リンク集

    • Pi は moltXYZ で最も注目されるべき部分だ
      Armin は明らかに時代を先取りしている
      Claude Code は今もフックとコンテキスト管理が浅い

  • 私はまだ Cursor を使っている
    Claude Code に移ろうとしたが、私の小さなコードベースでは Cursor のほうがずっと速い
    ただ、diff-review UI が Git と統合されていないので不便だ
    AI が作った変更と自分が作った変更を区別しにくく、Git 統合レビューのほうが重要だと感じる

    • Cursor の強みは 短いフィードバックループ だ
      Claude Code は結果を信じて任せる感じで不安になる
      モデルを自由に切り替えられることが重要だ。言語や作業の種類によってモデル性能が違う
    • VS Code 用の Claude Code 拡張 をインストールすれば、大規模コードベースの探索と CC 統合を同時に享受できる
    • Claude Code にはデフォルトでプロジェクトインデックスがないため、ファイルを一つずつ探索する
      私は起動時にファイル一覧をコンテキストへ入れるフックを作って速度を改善した
      複数ファイルを同時に編集するカスタムツールも作って約 3 倍速くなったが、一部の例外ケースのため無効化している
    • 私もブートストラップ中のソロ開発者で、Claude を 小さな作業の自動化 に活用している
      たとえばフロントエンドのテスト自動化やランディングページ修正などだ
      メイン機能は別の Claude インスタンスで緊密なフィードバックループの中で管理している
    • Cursor も改善中だ。まもなく AI が書いた行の追跡（blame） 機能が追加され、どのモデルがどのプロンプトで書いたか確認できるようになる

  • ミニマルなエージェントアーキテクチャ に関する記事が印象的だった
    「必要でなければ作らない」という哲学が気に入った
    私は OpenClaw を使って複数のワークフローを並列管理している — 顧客サポート、デプロイ監視、コードレビューなど
    重要なのは コンテキストエンジニアリング だ
    OpenClaw の workspace-first モデル は、AGENTS.md、TOOLS.md、memory/ ディレクトリによってセッション間の学習を継続する
    エージェントが自ら学習する過程をログで観察できる
    見せかけのセキュリティよりも、現実的な脅威モデルを認めるアプローチが良い
    複数の専門エージェントを並列に置くほうが汎用型より優れているという点にも共感する
    Pi と OpenClaw を Terminal-Bench で比較してみると面白そうだ

  • Armin Ronacher がなぜ Pi を使うのかについての文章が良かった
    Armin のポスト を見て、Pi が OpenClaw のエージェントハーネスだと初めて知った

  • Pi は JavaScript ベースの構造 なので、ブラウザサンドボックスアーキテクチャと相性が良い
    AI エージェントの今後の方向性に合っていると思う
    ただし著者には vendor extensions に対してもう少し柔軟であってほしい
    関連議論

    • 「共通部分を標準化し、和集合を露出させる」という表現が印象的だった

  • 私はまだ YOLO モード を使っていない
    ツーリングが出そろうまでにはあと 6 か月はかかりそうだ
    エージェントが任意のコマンドを実行する必要はほとんどない
    lint、検索、修正、Web アクセス程度を権限システムに統合できれば十分だ
    Deno や Workerd のようにサンドボックス化と権限制御があるランタイムなら第一防衛線になる
    だから Anthropic が Bun を選んだのは理解しがたい — セキュリティアーキテクチャがほとんどない