Pi coding agent を Switchyard につないで開発環境を組んでみた

はじめに

こんにちは、クラスメソッド製造ビジネステクノロジー部の森茂です。

普段の開発では Claude Code と OpenCode を使ってきましたが、最近は日常的に触るコーディングエージェントを Pi coding agent へ切り替えています。

https://pi.dev/

Pi は「Primitives, not features」を掲げる、小さなコアと拡張を中心にしたターミナル向けのコーディングエージェントです。MCP、サブエージェント、plan mode、permission popup といった機能を本体へ積み込まず、必要なら extension や package で選んで足します。この割り切りと TUI の軽快さが面白く、自分の作業環境に合わせて組み立ててみたくなりました。

一方で、モデルを呼び出す経路は変えていません。以前の記事で、OpenCode を NVIDIA NeMo Switchyard へ接続し、オープンウェイトモデルを strong と weak に分けて使うチーム AI 環境を紹介しました（2026-08-08 時点の記事です）。

https://dev.classmethod.jp/articles/open-weight-team-ai-environment/

今回は、そのモデル・ルーティング層を残したまま、開発者が触るクライアント層を Pi へ交換します。小さなコアに必要な拡張だけを足す形で、既存の Switchyard・Agent Skills・MCP 資産を持ち込めるかを組み立てながら見ていきます。あわせて、グローバルの AGENTS.md や Skills を載せたときに初回 input がどこまで増えるかも測っておきます。

この記事では、Pi を Switchyard へ接続し、Agent Skills、MCP、subagent、permission と常用のための小さな UI extension を足す構成を紹介します。オープンウェイトモデル中心の開発環境を保ったまま、コーディングエージェントの入口を交換したい人に刺さるといいなと思っています。

チーム AI 環境のクライアント層を Pi に替える

今回の構成を 1 枚にまとめると次のようになります。

普段のモデル呼び出しは Pi から Switchyard へ送り、role に応じて weak、strong、Kimi K3 の固定 route を使う。OpenAI subscription は router を通らない別経路として残している。

前の記事から変えたのは左側の開発者クライアントです。Switchyard の API、strong と weak のモデル、チーム共通の Agent Skills、RAG の MCP サーバはそのまま使います。

現在の構成では、通常の作業を auto、調査系の subagent を weak-only、レビューを strong-only、深い設計相談や画像入力を k3-only へ送ります。Switchyard の route ID を安定したインターフェイスとして扱うため、背後のモデルを差し替えても Pi 側の設定は変わりません。

前記事の公開時は Kimi K3 を strong tier に置いていましたが、現在の配布設定では weak-only が DeepSeek V4 Flash-0731、strong-only が DeepSeek V4 Pro-0813 で、k3-only は明示的に選ぶ固定 route です。この記事ではモデル選定の比較を繰り返さず、現在の設定をそのまま使います。

Pi は機能よりプリミティブを選んでいる

Pi の README は、既定の中心を read、write、edit、bash の 4 tool と説明しています。現行 CLI は grep、find、ls も built-in tool として持ち、起動時の tool は設定で絞れます。大事なのは数そのものより、ハーネスがワークフローを決めすぎない点です。

Pi が内蔵しない代表的な機能と、今回選んだ対応を並べました。

全部入りのハーネスから機能を無効化するのではなく、最初は小さく、必要になったものだけを選びます。自分で判断する範囲は増えますが、どこから挙動が追加されたのかを追いやすいのが気に入っているところです。

Pi 自身が extension、Skills、SDK のドキュメントを案内する作りになっているのも特徴です。欲しい動きがなければ、Pi に extension を書かせ、/reload でその場で読み直せます。ただし、変化の起点はユーザー側です。勝手に裏で機能が増えるのではなく、差分を見ながら自分の道具を組み立てる感覚に近いです。

system prompt が 1,000 tokens 未満でも成り立つ理由

Pi の system prompt は、tool 定義と合わせても 1,000 tokens を下回ります。作者の Mario Zechner 氏は設計解説の記事で、フロンティアモデルは agentic coding の RL 訓練を十分に受けており、コーディングエージェントとして何をすべきかをモデル自身がすでに理解している、と説明しています。数千 tokens 規模の system prompt を持つ Claude Code や Codex とは、ここで桁が 1 つ違います。

この説明を読んだとき、数年前との感覚のギャップが面白いなと思いました。LLM 登場初期は、役割設定や出力形式を長い前置きで細かく指定するプロンプトエンジニアリングが主流でした。「あなたは優秀なプログラマです」から始まる呪文で挙動を引き出していた時期ですね。その後モデルの instruction tuning と RL が進むにつれ、工夫の中心は「どう指示するか」から「何をコンテキストに入れるか」へ移っていきます。ゴールを与えて自律的に計画させる、tool の実行結果をループで返す、必要な文書だけを都度読み込ませる。いわゆるコンテキストエンジニアリングの流れです。

Pi の思想は、この変化を設計に反映したものだと受け取っています。エージェントとしての振る舞い方はモデルの重みに焼き込まれているので、ハーネスが毎回教え直す必要はない。ハーネスの仕事は、コンテキストへ入るものをユーザーが把握し、制御できるようにすることに絞る、という割り切りです。system prompt が小さいのは事前の指示が不要になったからではなく、常に必要な指示はモデル側へ移り、残る指示はタスクや環境ごとに変わるのでユーザーが選んで足すべきもの、という整理だと理解しています。

実際、後述するとおり自分の環境でも AGENTS.md と Skills の一覧で 3,000 tokens ほどを積んでいて、指示がゼロになったわけではありません。違いは、その全量を自分で説明できることです。プロンプトエンジニアリング期の呪文と違い、足した文脈は自分の運用資産なので、効かなければ削れますし、背後のモデルを替えても持ち越せます。この整理が腑に落ちたことが、Pi の思想がしっくりきた一番の理由です。

Pi を Switchyard へ接続する

インストールは普段の toolchain に合わせて bun を使いました。依存 package の lifecycle script を実行しない形にしています。

bun add -g --ignore-scripts @earendil-works/pi-coding-agent
pi --version

Switchyard 側は、以前の記事で紹介した配布 bundle を利用します。Pi 用の onboarding と example 設定も同じリポジトリへ追加しています。

https://github.com/himorishige/switchyard-opencode-bundle

~/.pi/agent/models.json に OpenAI Chat Completions 互換の provider を定義します。以下は要点だけを抜き出した例です。

{
  "providers": {
    "switchyard": {
      "baseUrl": "http://127.0.0.1:4100/v1",
      "api": "openai-completions",
      "apiKey": "local-dummy",
      "models": [
        { "id": "auto", "input": ["text"] },
        { "id": "weak-only", "input": ["text"] },
        { "id": "strong-only", "input": ["text"] },
        {
          "id": "k3-only",
          "reasoning": true,
          "input": ["text", "image"]
        }
      ]
    }
  }
}

apiKey は Switchyard をローカルで使うためのダミー値です。Pi は認証情報がない provider を /model の利用候補に出さないため、キーを検査しないローカル endpoint でも値を置きます。外部 API のキーを直接書く用途ではありません。

上の例は普段使う 4 route だけを抜粋しています。配布 bundle の pi-models.json.example には auto-esc と qwen3.7-plus を含む 6 route が定義されています。auto-esc は weak から開始する非対話向けの昇格経路、qwen3.7-plus は画像入力に対応する固定経路です。

記事の標準構成では、settings.json の既定を Switchyard の auto にします。

{
  "defaultProvider": "switchyard",
  "defaultModel": "auto",
  "enableInstallTelemetry": false,
  "enableAnalytics": false
}

設定後は 6 route が見えました。

provider    model         context  max-out  thinking  images
switchyard  auto          262.1K   16.4K    no        no
switchyard  auto-esc      262.1K   16.4K    no        no
switchyard  k3-only       262.1K   16.4K    yes       yes
switchyard  qwen3.7-plus  262.1K   16.4K    no        yes
switchyard  strong-only   262.1K   16.4K    no        no
switchyard  weak-only     262.1K   16.4K    no        no

この一覧の context と max-out は Switchyard から自動取得した値ではなく、models.json に設定した contextWindow: 262144 と maxTokens: 16384 です。Switchyard の /v1/models は現在 context_window: null を返します。一方、背後の Fireworks API では Flash-0731、Pro-0813、Kimi K3 の context_length は 1,048,576、Qwen3.7 Plus の公式モデルページは 262k tokens と案内されています。

主要モデルのバックエンド能力は 1M tokens ですが、session の肥大化を抑え、route 間の扱いを揃えるため、Pi 側は全 route を 262K で運用しています。Pi はこの値から応答用の予約領域を引いた時点で自動 compaction を判断します。既定の 16,384 tokens を予約する現在の構成では、境界は 245,760 tokens です。16.4K はバックエンドの最大出力ではなく、Pi から 1 回の応答で要求する最大値です。

TUI では /model、または Ctrl+L から route を切り替えられます。普段は auto のまま使い、用途が明確なときだけ固定 route を選ぶ形です。

Agent Skills と prompt template を引き継ぐ

Pi は Agent Skills 標準に対応し、グローバルの ~/.agents/skills/ と project の .agents/skills/ を探索します。一例として、自分の環境では、この ~/.agents/skills/ を Claude Code、OpenCode、Codex、Pi から見る共通ハブにしています。

たとえば web 検索の手順は web-search Skill、社内ナレッジ検索の作法は rag-kb Skill に置きます。ハーネスごとに同じ説明を複製せず、SKILL.md の実体を 1 つに保つ方針です。

同じく一例として、プロジェクト固有の明示コマンドは .pi/prompts/ の prompt template に置きました。このワークスペースでは /context-load <project> と /context-save <project> が該当します。実際の手順は .agents/skills/project-context/ を正本とし、Pi の template は毎回その reference を読む薄い入口です。

この分け方にすると、判断が必要な能力は Skill、ユーザーが明示的に呼ぶ定型操作は prompt template、常に守るルールは AGENTS.md と役割が分かれます。Pi のコアを変更しなくても、既存の運用資産をそのまま持ち込めました。

足りない機能は package で選んで足す

初回の環境では 4 つの package を中心に追加しました。バージョンは 2026-08-16 の実測です。

導入には Pi の package manager を使います。

pi install npm:pi-mcp-adapter
pi install npm:pi-subagents
pi install npm:@gotgenes/pi-permission-system
pi install npm:@narumitw/pi-btw

pi-mcp-adapter は、登録した MCP tool の schema をすべて最初から展開せず、単一の mcp tool から status、search、tool の順に必要なものだけを見つけます。自分の環境では、weak model がこの discovery を通って RAG 検索まで進めました。MCP サーバが増えても入口の tool 定義を小さく保てるため、weak tier と組み合わせやすい構成です。

pi-subagents は scout、researcher、worker、reviewer、oracle などの role を提供します。Pi 本体へ唯一の subagent 設計を焼き込まず、必要な workflow を package 側で選べるという、Pi らしい追加方法です。

ここからは、package を入れた後に常用時の引っかかりを減らすために追加した UI 周りを見ていきます。

常用するための UI を extension で整える

MCP や subagent が動いても、毎日使う画面が情報過多だと作業へ集中しにくくなります。画面や挙動を足す実体は extension で、package はその配布単位です。前章の pi-btw も package から入れた extension で、/btw を打つと主会話へ混ぜずに短い質問を投げられます。ここへ、自分で書いたものと Pi の example を変更したものを重ねています。

questionnaire と plan-mode は Pi が提供する extension example を起点にしています。plan mode には、生成した plan を project 配下へ保存する処理と、既存ファイルや project 外を上書きしない検査を足しました。

自作部分と変更した example は、Switchyard の配布 bundle へ混ぜず、独立した Pi package にまとめました。次のコマンドでまとめて導入できます。

pi install git:github.com/himorishige/pi-coding-agent-extensions

https://github.com/himorishige/pi-coding-agent-extensions

Bash 出力と Footer を必要な情報だけに絞る

focus-ui は、成功した Bash のコマンドと出力を折りたたみ時に隠し、失敗時だけコマンドとエラーを残します。詳細が必要なときは Ctrl+O で展開できます。

Footer には、利用中のモデルと thinking level を model:level 形式で表示します。続けて作業ディレクトリ、Git branch、staged・modified・untracked の件数を置き、右端にはコンテキスト使用率と compaction 回数を表示します。使用率が 80% 以上になるとバーを赤へ変えるため、次の compaction が近いことも画面下部だけで判断できます。

Footer の例。GPT-5.6 Sol:high のようにモデルと thinking level を並べ、右端では 90% のコンテキスト使用率を警告色で表示している。

Turn Recap から次の作業へつなぐ

turn-recap には、追加のモデル呼び出しを行わない fast mode と、要約と次の作業案をモデルに書かせる smart mode を持たせました。現在は smart mode を使っています。

{
  "mode": "smart",
  "model": "openai-codex/gpt-5.6-luna",
  "thinkingLevel": "low",
  "timeoutMs": 30000
}

変更ファイルと検証結果は tool の実行履歴から取り出し、モデルには要約と次の作業案だけを任せています。要約は別の completion なので、メインの会話履歴は汚れません。Recap が出した次の作業は、確認してから入力欄へ送れます。

subagent ごとに使う route を固定する

Switchyard の自動ルーティングにすべてを任せず、役割が明確な処理は Pi 側で route を固定しています。

{
  "subagents": {
    "defaultModel": "switchyard/weak-only",
    "agentOverrides": {
      "reviewer": {
        "model": "switchyard/strong-only"
      },
      "oracle": {
        "model": "switchyard/k3-only"
      }
    }
  }
}

scout と researcher はファイル探索や web 検索が中心なので weak 固定、reviewer は strong、設計判断を相談する oracle は Kimi K3 にしています。通常のメイン対話は auto のままです。

この記事の公開情報調査も researcher に委譲し、Switchyard の weak-only へ流しました。公式資料を調べる役割に高価な model を固定せず、成果物のレビューが必要なところだけ strong を使えます。

model provider の障害時には、role ごとに OpenAI Codex の fallback model も設定できます。ただし、この fallback は Switchyard を通らないため、チームの利用量を集計するときは別経路として扱います。

permission と sandbox の境界を押さえる

Pi は permission popup を本体へ内蔵せず、起動ユーザーの権限で tool を実行します。公式 README も、必要なら extension で確認処理を作るか、コンテナなど実行環境側で隔離する方針を示しています。

ここで分けて考えたいのが、Project Trust、permission、sandbox の 3 つです。

pi-permission-system の smoke では、.env の path deny と headless の fail-closed は意図どおり動きました。一方、特定の削除コマンドを deny しても、モデルは別のコマンド形式で同じ目的を達成できました。文字列パターンは形式に効きますが、意図そのものを隔離する仕組みではありません。

また、Pi package と extension はユーザー権限で任意コードを実行できます。package を追加する前にソースを確認し、初めて開く repository では Project Trust の確認を飛ばさないことが前提です。現在は trusted workspace で permission rule を重ねていますが、より強い分離が必要な作業はコンテナや sandbox へ送る構成を検討しています。

初回 input は足したものだけ増える

Pi のコアが小さいことと、実運用の初回 input が常に小さいことは別です。空の一時ディレクトリで同じ prompt と weak-only を使い、extension と prompt template を無効にして測りました。workspace-dgx の AGENTS.md や project Skills は読み込んでいません。

この条件では、グローバルの AGENTS.md が 179 tokens、起動時に列挙される Skill の name と description が 2,992 tokens、合計で 3,171 tokens 増えました。Skill 本文は task に一致したときに読み込む progressive disclosure なので、この数値には含まれません。

Switchyard への接続自体は、auto の headless 実行と画像を付けた k3-only でも status 200 で完走しています。

Pi のコアは小さいままですが、AGENTS.md や利用可能な Skill の説明を追加すれば、その分だけ入力は増えます。「小さいハーネスを選んだから何を足しても軽い」のではなく、追加した文脈を自分で説明できるのが Pi の良さだと捉えています。

OpenAI サブスクリプションは別経路として残す

Pi は /login から ChatGPT Plus / Pro、Claude Pro / Max、GitHub Copilot の subscription auth を追加できます。契約中プランの利用枠で使える model が /model に並ぶため、Switchyard と同じ TUI から切り替えられます。

今回の構成では、OpenAI subscription を通常経路にはしていません。普段の作業と subagent は Switchyard に寄せ、オープンウェイトモデルの利用実績を routing log に残します。subscription を使うのは、provider 障害や別 provider での確認と、turn recap の要約のようにメインの会話から外れた補助的な処理だけです。

この線引きにした理由は、技術的に両方を使えることと、運用上どちらを本線にするかは別だからです。subscription model を直接呼ぶと Switchyard の classifier を通らず、routing log にも残りません。チーム環境として数字を追うなら、通常経路を 1 本に決めておくほうが後から説明しやすくなります。

まとめ

Pi coding agent を Switchyard へ接続し、Agent Skills、MCP、subagent、permission、常用のための UI extension を選んで追加する開発環境を紹介しました。モデル・ルーティング層は前記事の構成を維持し、開発者が触るクライアントだけを Pi へ交換しています。

Pi の面白さは、単に system prompt が小さいことではなく、どの機能をどの境界から追加したかを追えるところにあると感じています。実運用では AGENTS.md と Skills を積むため初回 input も増えますし、permission を追加しても sandbox の代わりにはなりません。このあたりを隠さず、自分の用途に必要なものだけを足していけるのが、日常利用を切り替えた理由です。

次はほぼ確認なしで動く Pi の性格を活かして、NVIDIA OpenShell のような sandbox 環境で走らせる構成も試してみたいですね。

参考リンク

• Pi coding agent
• earendil-works/pi
• The Pi Coding Agent — Mario Zechner 氏による設計思想
• NVIDIA-NeMo/Switchyard
• Qwen3.7 Plus - Fireworks AI
• Kimi K3 - Fireworks AI
• switchyard-opencode-bundle — Pi onboarding と example 設定を収録
• pi-coding-agent-extensions — 常用している UI extension と変更した example
• pi-btw — 主会話を汚さない side question extension
• オープンウェイトモデルで開発からビジネス利用まで回すチーム AI 環境