ハクソク

世界を動かす技術を、日本語で。

意見を持ち、ミニマルなコーディングエージェントを構築して学んだこと

113日前原文(mariozechner.at)

概要

  • pi-ai と pi-agent-core の開発背景と設計思想の解説
  • 複数LLMプロバイダ対応の 統一API を実現するための課題と工夫
  • コンテキスト管理 や ツール呼び出し の具体的な実装例
  • TUI（ターミナルUI） や最小限のコーディングエージェントCLIの開発
  • 商用製品との比較や、個人開発ならではのシンプルさの追求

2025年のコーディングエージェント進化と「pi」シリーズ開発記

  • ここ3年間、 LLMを活用したコーディング支援 を模索
    • ChatGPTへのコピペから始まり、Copilot、Cursor、Claude Code、Codex、Amp、Droid、opencodeなどを試用
  • Claude Code 初期バージョンの シンプルさ が好み
    • 機能追加で複雑化し、 ワークフロー崩壊やUIのちらつき に不満
  • 独自エージェント（例：Sitegeist）も複数開発
    • コンテキスト設計の重要性 を痛感
  • 既存ハーネスの ブラックボックス化 や セッション記録の不透明さ に課題
  • 自分用に必要最小限 のコーディングエージェント「pi」シリーズを開発決意

pi-aiとpi-agent-coreの設計哲学

  • pi-ai ：複数LLMプロバイダ対応の 統一API を実現
    • Anthropic, OpenAI, Google, xAI, Groq, Cerebras, OpenRouterなどをサポート
    • ストリーミング・ツール呼び出し・コスト管理 などに対応
  • pi-agent-core ：ツール実行・バリデーション・イベントストリーミングを管理
  • pi-tui ：最小限のターミナルUIフレームワーク
    • 差分レンダリング・ちらつきの少ない出力・エディタやMarkdown表示など
  • pi-coding-agent ：CLIで一連の機能を統合
    • セッション管理・カスタムツール・テーマ・プロジェクトコンテキスト対応
  • 「不要なものは作らない」 というミニマリズム重視

LLM API統一の現実と課題

  • 実質 4種類のAPI で主要LLMプロバイダを網羅可能
    • OpenAI Completions/Responses, Anthropic Messages, Google Generative AI
  • 各プロバイダの 細かな仕様差 に個別対応が必要
    • 例：max_tokensのパラメータ名やシステムプロンプト対応の違い
  • テストスイート で多様な入力やツール呼び出しを網羅的に検証
  • トークン管理・コスト計算 はプロバイダごとにバラバラで完全な精度は困難
  • Googleは ツールコールのストリーミング未対応

コンテキストハンドオフの実装

  • セッション中に 異なるLLMプロバイダへ切り替え可能
    • 例：Anthropic→OpenAI→Googleと順に切り替え
    • 各プロバイダの「思考トレース」や特殊イベントを ベストエフォートで変換
  • シリアライズ/デシリアライズ によるセッション保存・再開
  • クロスプロバイダでの一貫性維持 に苦労しつつも、実用レベルで動作

マルチモデル世界への対応

  • モデル情報を TypeScript型 として管理
    • OpenRouterやmodels.devから情報を自動生成
    • 自己ホスト型モデルや新規プロバイダ も簡単に追加可能
  • リクエスト中断（abort）や部分的結果取得 に最初から対応
    • 生産環境統合やUIフィードバックに必須

ツール出力の構造化分割

  • ツール実行結果を LLM用（テキスト/JSON） と UI表示用 に分割
    • UIでの表示最適化が容易
  • 画像などの添付ファイル にも対応
  • バリデーションやエラー処理 も自動化

まとめ

  • 既存コーディングエージェント の複雑化・ブラックボックス化へのアンチテーゼ
  • 個人用途に最適化 したシンプル・拡張性重視の設計
  • pi-aiシリーズ は「自分が欲しい機能だけ」を徹底追求
  • 開発者体験・透明性・UI拡張性 のバランス重視

このように、「pi」シリーズは 複数LLMプロバイダの統一的活用 と 個人開発者向けのシンプルな体験 を両立するための独自アプローチを実現しています。

Hackerたちの意見

Piは多分、最高のアーキテクチャを持ってるし、JavaScriptで書かれてるから、AIエージェントの未来にぴったりなブラウザのサンドボックスアーキテクチャを活かせると思う。著者がベンダー拡張についてのスタンスを変えてくれたらいいんだけど。 https://github.com/badlogic/pi-mono/discussions/254

└

「交差点を標準化し、ユニオンを公開する」というフレーズ、今まで聞いたことなかったけど、すごくいいね。

他のコーディングエージェントのセキュリティ対策を見てみると、ほとんどがセキュリティシアターだよね。エージェントがコードを書いて実行できるようになったら、ほぼ終わりだよ。少なくともCodexの場合、エージェントはOSが提供するサンドボックス内でコマンドを実行するから（macOSのSeatbeltとか、他のプラットフォームの色々）、あまり「エージェントがほとんど役に立たなくなる」ことはないよ。

└

私のCodexは、SDKをパスの外でパッチするように頼むと、サンドボックス内でファイルを作成するためにPythonを使ってる。

└

CodexはClaude Codeみたいにランダムにサンドボックスを無効にするの？

└

エージェントをコンテナの外で動かすのはマジでやめた方がいいよ。それは基本中の基本。

└

非読取ツールの呼び出しには承認が必須にすべきだと思う。LLMが何をしようとしているのか、すべて読んで手動で承認するべきだ。「でも、それは面倒で時間がかかる！」そうだね、でも災害的なツール呼び出しから回復するのも時間がかかるよ。

└

このワークフローを理解しようとしてるんだけど、コーデックスを使い始めたばかりで、まだ2日目なんだ。GitHubのリポジトリに接続して、クラウドで動かしてプルリクエストを作成してる。UIとミドルレイヤーのコードだけ触るようにしてて、データベースの変更は一切なし。モデルには触れないようにいつも指示してるよ。

もう何人かのパワーユーザーがPiに移行してるのを見たし、私も考えてるところ。前提がすごく魅力的だよね。 - 最小限で設定可能なコンテキスト - システムプロンプトを含む [2] - 最小限で拡張可能なツール；例えば、タスク管理の拡張 [3] - 組み込みのMCPサポートはなし；拡張機能は存在する [4]。私はmcporterを使いたいな [5]。コンテキストを完全にコントロールできるのは、高いレバレッジ能力だよ。パフォーマンスに対するコンテキストの多くの制限（インコンテキストリトリーバルの制限 [6]、コンテキストロット [7]、コンテキストドリフト [8] など）を理解していれば、Piが全体のコンテキストを最適なパフォーマンスのために微調整できることを本当に評価できると思う。明らかに誰にでも向いてるわけじゃないけど、その力強さは感じられるよね。 --- [1] https://lucumr.pocoo.org/2026/1/31/pi/ [2] https://github.com/badlogic/pi-mono/tree/main/packages/codin... [3] https://github.com/mitsuhiko/agent-stuff/blob/main/pi-extens... [4] https://github.com/nicobailon/pi-mcp-adapter [5] https://github.com/steipete/mcporter [6] https://github.com/gkamradt/LLMTest_NeedleInAHaystack [7] https://research.trychroma.com/context-rot [8] https://arxiv.org/html/2601.20834v1

└

PiはmoltXYZの中でバイラルになるべき部分だね。Arminはここでかなり先を行ってる。Claudeのサブが私をClaude Codeに留めてる唯一の理由だよ。前よりはマシになったけど、フックやコンテキスト管理のサポートはまだまだ表面的だね。

コードをChatGPTにコピー＆ペーストしたり、Copilotの自動補完を使ったり、Cursorを経て、最後にはClaude CodeやCodex、Amp、Droid、opencodeみたいな新しいタイプのコーディングエージェントが登場してるね。HNを読んでると、なんか置いてけぼりな気分になる。みんなが言うようにClaude Codeに移行しようとしたけど、なんかしっくりこないんだよね… もしかしたら、コードベースの大きさが原因かも。今、独りで開発してるスタートアップを始めて6ヶ月だから、そこまで大きなものはないし、Cursorを使えばすごく早く反復できる。ほとんどがSPAのブラウザでクリックテストしたものだし。比較すると、Claude Codeは何かをするのに永遠にかかる気がする。（とはいえ、CursorのUIは時々イライラする。特に、AIの変更の差分レビュー（赤/緑）がgitに統合されてないのがね。gitに統合されたもの（ステージ済みと未ステージのハンク）を使ってくれた方が良かったな。どの変更が自分のもので、どれがAIのものかを覚えるより、良いコードレビュー体験の方が大事だと思うし。）

└

あなたにとって理想的な妥協案は、VS Code用の公式Claude Code拡張機能をインストールすることかも。そうすれば、大規模で複雑なコードベースをナビゲートするためのIDEを持ちながら、CCの統合もできるよ。

└

ブートストラップしたソロ開発者だよ。重要なタスクの下にあるTODOリストの小さなことをClaudeを使って片付けるのが楽しかった。例えば、ランディングページの更新とか、あなたの場合はフロントエンドの自動テストを追加すること（自分でクリックしなくて済むように）。誰かが提案を出してくれるのはいいよね。完璧じゃなくても、スタートとしては良いと思う。メイン機能を実装するためにClaudeのインスタンスを一つ動かしていて、フィードバックループがタイトだから、何をしているのか正確にわかる。確かに、時々時間がかかるけど、他のClaudeが何をしているか確認する時間として使ってるよ。

└

僕にとってCursorはClaude Codeよりもずっとタイトなフィードバックループを提供してくれる。必要なものを得るために、レビューして元に戻したり、モデルを変更したりできる。時々、Claude Codeはエージェントに何を生産するかをもっと信頼しなきゃいけないYOLOオプションとして提示されてる気がする。モデルを変更する能力は重要だと思う。フロントエンドの設計が得意なモデルもあれば、そうじゃないモデルもあるし、異なるプログラミング言語やコピー、ブログを書くのが得意なモデルもある。すべてのフロンティアオプションで同じプロンプトとコンテキストを試すためにモデルを簡単に切り替えられないと、サボタージュされてる気分になる。

└

Claude Codeはほとんどファイルをいじってるだけだよ。デフォルトではプロジェクトの知識は持ってないし（ファイルインデックスとかもない）、最近変わったのかもしれないけど。私がよく使ってた時は、スタートアップフックを作って、ファイルリストをコンテキストに流し込んでた。小さいリポジトリでは実際のフルコードも。カスタム編集ツールを使うと、複数のファイルの複数のチャンクを同時に編集できて、3倍速かったんだ。ただ、いくつかのエッジケースで壊れたこともあったから、結局それを無効にしちゃった。

OpenClaw/pi-agentの状況は、ollama/llama-cppに似てるね。前者がすごく注目されてるけど、実際には後者の方が印象的だと思う。素晴らしい仕事だし、今後の進化が楽しみ。今のところ、バグがあるけどClaude Codeが一番良さそうだね。寛大なサブスクリプションを考えると。でも、市場が修正されて価格がAPIの価格に近づくと、最適化された体験を持つトークンごとのプレミアムの方が、Claude Codeのバグや小さなストレスを我慢するよりも良い取引になると思う。結局、カスタマイズ可能でエージェントによって再帰的に改善できるエージェントフレームワークキットの方が、硬直したプロプライエタリのクライアントアプリよりも良いって気づくよね。

└

でも市場が修正されて価格がAPIの価格に近づくと、APIの価格が時間とともに下がる可能性が高いと思うし、CCの許可はもっと寛大になるだけだと思う。LLMの価格上昇についての予測は何年も聞いてきたけど、推論のユニットエコノミクス（トレーニングを除く）は、多くの人が思っているよりもずっと良いし、R&Dへの資金は不足していないと思う。Claude Codeが今のままで小さなバグがある状態を維持するとは思わない。すべてのツールは時間とともに改善されるよ。僕の経験では、競合するツールもバグがないわけじゃないけど、アンダードッグの地位のおかげで許されてる。すべてのツールは改善していくし、これからもそうなるだろうね。

└

これって、ChatGPT/GPT-3の状況とほぼ同じだよね ;) OpenAI自身も「なんでChatGPTがこんなに人気なのか分からない」って言い続けてるし… GPTは何年も前からAPIで使えたのにね！

└

参考までに、piでサブスクリプションを使えるよ。OpenAIがpiを認めて、ユーザーが自分のGPTサブスクリプションを使えるようになってる。他のプロバイダーも同じだけど、Flicker Companyは除いてね。個人的には、ピーターのプロジェクトが注目されてるのがすごく嬉しい。piのリポジトリは、openclawユーザーからのPRがすでに十分あるし、それでもopenclawのリポジトリが抱えてる苦労の1/100にも満たないからね。

特別にGoogleに感謝したい。今のところツール呼び出しストリーミングをサポートしていないのは、まさにGoogleらしい。Googleはローカルでトークンをカウントするためのトークナイザーすら提供していない。これによる愚かさの結果は、プロンプトボックスに入力するたびにcount_tokensのAPI呼び出しを行うAIスタジオで直接見られる。

└

それに、Anthropicもそうだよ。

彼が自分のスキルを基本的に作り出してるのに混乱したけど、これは2025年11月の話だから、スキルがまだ新しかった時期だし、納得できるね。それに、今はこのターミナルベンチのリーダーボードには全く載ってないから、ここを読んでるみんなにはその点を気をつけてほしい。これは使うためのCLIじゃないよ。良い実験とレポートって感じ。

新しいpiコーディングエージェント（あるいはClaude Codeの代替品）に切り替えてない主な理由は、価格なんだ。トークンを朝昼晩食べてる感じ。月額100ドルのプランに入ってるけど、コーデックスバーを見ると、30日ごとに500ドル近く使ってるように見える。Qwen 3（コーディング）をBlackwell Pro 6000でローカルで試してみたけど、まだ少し遅れてる感じがするし、Claude Codeを完全に手放すにはちょっと物足りない。みんなはどう思ってるのかな？ローカルモデルで他のエージェントの成功事例とかある？それともほとんどプロプライエタリモデルにこだわってる？Claude Codeにちょっと縛られてる気がする。高いけど、すごく良いから困る。

└

彼らがブレイクイーブンのコストに近いとは思えないね。

マリオのtmuxを使って長時間実行するコマンドについての意見が特に良かったな。モデルがtmuxからの読み書きが得意だってことに気づいたから、REPLでセッションを立ち上げて、Claudeを使って何かをプロトタイプして、それをREPLでさらに深く調べるってことをやってるよ。

こういう話から感じるのは、意見が強いデザインと実際の使い勝手との間の緊張感だね。特にエージェントベースのツールやアシスタントみたいなミニマルなものを作るとき、単に表面積を減らすだけじゃなくて、ユーザーの問題を実際に解決することに焦点を当てるのが大事なんだ。エッジケースだけを扱うミニマルなエージェントや、制約の厳しい環境でしか動かないものは、見た目はスマートでも実際には使いにくいことがある。一方で、少しミニマルさが減っても、明確さや意図を保っているシステムの方が、膨れ上がることなく、より役立つことが多いよ。分析や解釈を伴うツールを立ち上げた経験から言うと、理想的なポイントはいつも以下の交差点にあるんだよね： - 明確にスコープされたコアバリュー、 - 意図的に制限された表面、 - 実際のユーザーのバリエーションに対応できる十分な柔軟性。自分のプロジェクトでエージェントや抽象化をデザインする際に、ミニマリズムと実用性のバランスをどう考えてるのか、他の人の意見も聞いてみたいな。

└

[遅延]