Pi Coding Agent 導入ガイド 2026：npm インストール、API Key、Claude/GPT/Gemini と TypeScript 実戦

なぜ「また次の IDE Agent」ではマルチモデルが解決しないのか

2026年、多くのチームの痛みは「Agent がない」ことではない。鍵・モデル・実行環境が同一プロダクトに縛り付いていることだ。Claude Code は Anthropic サブスクを食い、Codex CLI は ChatGPT を食い、Cursor はモデル選択をエディタアカウントの奥へ隠す。午後は Claude で設計を直し、夜は Gemini でテストを洗い出し、週末は GPT でコミット文を書く——つもりが、毎回ウィンドウ・権限・コンテキストを丸ごと取り替えることになる。

Pi はこの前提を分解した。公式の位置づけは最小 harness：デフォルトでモデルに渡す道具は read、write、edit、bash の四つだけ。sub-agent、plan mode、権限ゲート、MCP など「他社が内蔵している機能」は拡張、Skills、Pi Package に回し、ワークフロー側で足す。モデルは差し替え可能なバックエンドであり、プロダクト本体ではない。

非対称な結論はこうだ：分水嶺は Claude、GPT、Gemini のどれが強いかではなく、harness がモデルを差し替え可能な実行バックエンドとして扱い、自分の TypeScript プロジェクトへ埋め込めるかどうかだ。 上げるべきは入口（CLI / SDK / RPC）、認証情報の分層、常時稼働の実行ノードであり、また一つ厚い IDE ではない。サイト内で「harness とは何か」を概念から分解した記事は Omnigent Agent Harness 完全理解。本記事は「Pi を入れ、三社の鍵を繋ぎ、リポジトリへ書く」ことだけを片付ける。

Pi とは何か：最小 harness の四つの入口

先に分類し、それからコマンドを語る。Pi はまた一つのチャット窓ではなく、同じ Agent ループを開く四つの方法だ。分類軸は入口・実行・コンテキスト・適した利用者層のままにする。

公式の哲学は短い。harness を変えよ、自分のワークフローを変えるな。拡張は TypeScript モジュールで、ツール、スラッシュコマンド、ショートカット、TUI 部品を登録できる。Skills は必要になったときだけ読み、最初から prompt cache を膨らませない。パッケージは pi install npm:@scope/pkg または pi install git:host/user/repo。能力の完全一覧は pi.dev と npm パッケージ説明が基準。バージョン番号は動く。安定するのは「何月何日のモデル名」より、コマンドの形だ。

Pi vs 閉じた Agent：入口・実行・コンテキスト

選定を「Claude が強いか、GPT が強いか」から始めると、本当の差を見逃す。Pi、公式 CLI、IDE Agent を同じ表に載せ、入口・実行・コンテキスト・適した利用者で揃えると、結論はほぼ即座に反転する。順位表を作り直す必要はない。本記事が答えるのは「鍵をプロダクトから切り離すべきかどうか」だ。

Claude Code と Codex をリモート Mac でどう選ぶかは、Claude Code vs Codex：リモート Mac 開発環境の選び方 を参照。あちらは「公式 CLI の選び方」。こちらは「マルチモデルが決まり、ループを TypeScript へ埋め込むと決めたあと、harness をどう入れるか」だ。

npm インストールと API Key 設定

グローバル CLI：先に対話できること、それから埋め込み

公式は --ignore-scripts 付きのグローバルインストールを勧める。Pi の通常利用は依存パッケージの install ライフサイクルスクリプトに頼らない。スクリプトを飛ばせばサプライチェーンの事故面が減る。Node バージョンは手元の LTS に合わせる。リポジトリが宣言する engines はパッケージ更新で動く。ブログ記事のマイナー番号を契約書に写してはならない。

npm install -g --ignore-scripts @earendil-works/pi-coding-agent
# または：pnpm add -g --ignore-scripts @earendil-works/pi-coding-agent
# または：bun add -g --ignore-scripts @earendil-works/pi-coding-agent
# インストーラ代替：curl -fsSL https://pi.dev/install.sh | sh
pi --version

入れたら先に二点。PATH に pi があること。使う予定のプロバイダに、少なくとも一本の鍵か一回の /login があること。認証が無いと TUI は開くが、モデルカタログで走れる項目は空になる。

鍵の分層：環境変数、auth.json、一回限りの上書き

公式の認証解決順は、コマンドライン --api-key → ~/.pi/agent/auth.json → プロセス環境変数 → models.json 内のカスタムプロバイダ鍵。対話の /login は OAuth または API Key を auth.json へ書く（ファイル権限 0600）。auth.json は環境変数より優先し、「このマシンでは長期的にこの鍵」向き。環境変数は CI と一回限りの実験向き。SDK の setRuntimeApiKey はプロセス内上書きで、ディスクに残らない。テストとマルチテナントホスト向きだ。

export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...
export GEMINI_API_KEY=...   # auth.json の対応キー名は google

pi
# 対話：/login でプロバイダを選ぶ；/model または Ctrl+L で切替；Ctrl+S で起動時デフォルトに保存

{
  "anthropic": { "type": "api_key", "key": "sk-ant-..." },
  "openai": { "type": "api_key", "key": "sk-..." },
  "google": { "type": "api_key", "key": "..." }
}

key フィールドは $ENV_VAR 補間と、!op read 'op://…' のようなコマンド取得も受け付ける（プロセス内キャッシュ）。リモートやヘッドレス機で、OpenRouter 系のブラウザコールバックが通らない場合、公式は最終リダイレクト URL または認可コードをログインプロンプトへ貼れと求める——SSH 上のクラウド Mac では特に多い。プロバイダ対照は providers.md が基準。

Claude、GPT、Gemini を接続する

Pi は組み込みプロバイダごとに「ツールを走らせられる」モデルカタログを持つ。設定済みカタログは自動更新され、pi update --models で強制取得もできる。認証はサブスク（Claude Pro/Max、ChatGPT Plus/Pro Codex、GitHub Copilot）でも API Key でもよい。切替は /model、Ctrl+L。常用モデルは Ctrl+P で巡回。/scoped-models が巡回名簿を決める。

pi --list-models claude
pi --list-models gpt
pi --list-models gemini

pi --provider anthropic --thinking high "src/ 内のループをテスト可能な関数に書き換える"
pi --model openai/gpt-4o -p "このリポジトリのエントリモジュールを三文で要約する"
pi --provider google -p "読み取り専用：カバーされていないテストファイルを列挙する"

# セッション内切替。再インストールは不要
# /model   または Ctrl+L
# Ctrl+P   scoped 名簿を巡回

モデル ID はカタログ更新で変わる。公式例には claude-opus-4-5、claude-sonnet-4-5、gpt-4o、gpt-5.1 が出てきた。本番では pi --list-models と SDK の getAvailable() を基準にし、ブログのスナップショット ID を本番スクリプトへ写さない。カスタムゲートウェイ（Ollama、vLLM、社内プロキシ）は ~/.pi/agent/models.json。相手が OpenAI / Anthropic / Google いずれかの API を話すことが前提。OAuth や独自プロトコルは拡張で扱い、CLI を無理に書き換えない。

本当に欲しいのが「自分で HTTP を書き、自分で JSON を解析する」なら、それは Function Calling 層であり harness 層ではない。対照は Function Calling と JSON API と GPT-5.6 API 完全ガイド：あちらはプロバイダを直接叩く。こちらは Pi にツールループを任せ、バックエンドだけを換える。

TypeScript プロジェクト実戦

CLI が解くのは「人がターミナルで指揮する」こと。SDK が解くのは「リポジトリ内のスクリプトも指揮できる」こと。SDK は同じ npm パッケージに同梱され、別インストールは不要。最小の閉ループは、ローカル依存 → 三本の鍵は環境だけへ → ModelRuntime でモデル選択 → createAgentSession で読み取り専用タスクを一回 → dispose()。

npm init -y
npm install @earendil-works/pi-coding-agent
# package.json に "type": "module" を追加

import {
  createAgentSession,
  ModelRuntime,
  SessionManager,
} from "@earendil-works/pi-coding-agent";

const runtime = await ModelRuntime.create();

if (process.env.ANTHROPIC_API_KEY) {
  await runtime.setRuntimeApiKey("anthropic", process.env.ANTHROPIC_API_KEY);
}
if (process.env.OPENAI_API_KEY) {
  await runtime.setRuntimeApiKey("openai", process.env.OPENAI_API_KEY);
}
if (process.env.GEMINI_API_KEY) {
  await runtime.setRuntimeApiKey("google", process.env.GEMINI_API_KEY);
}

const preferred =
  runtime.getModel("anthropic", "claude-opus-4-5") ??
  runtime.getModel("openai", "gpt-4o") ??
  (await runtime.getAvailable())[0];

if (!preferred) {
  throw new Error("利用可能なモデルがありません。先に三社いずれかのキーを export するか、pi --list-models を実行してください");
}

const { session } = await createAgentSession({
  model: preferred,
  thinkingLevel: "low",
  tools: ["read", "bash"],
  sessionManager: SessionManager.inMemory(),
  modelRuntime: runtime,
});

try {
  session.subscribe((event) => {
    if (
      event.type === "message_update" &&
      event.assistantMessageEvent.type === "text_delta"
    ) {
      process.stdout.write(event.assistantMessageEvent.delta);
    }
  });
  await session.prompt(
    "読み取り専用：カレントディレクトリの TypeScript エントリファイルを列挙し、テストが最も欠けていそうな箇所を一つ指摘せよ。ファイルは変更しないこと。"
  );
} finally {
  session.dispose();
}

このコードは意図してツールを read ＋ bash に絞り、セッションはメモリ、ディスクへ残さない。CI のレビュースクリプトがデフォルトで write/edit を持つべきではない。永続セッションが要るなら SessionManager.create(process.cwd())。CLI と同じ長期鍵を共有するなら setRuntimeApiKey は呼ばず、runtime に ~/.pi/agent/auth.json を読ませる。auth パスを独自にするなら authPath / modelsPath をアプリ自身のディレクトリへ向け、複数サービスが同じホームファイルを奪い合わないようにする。SDK イベント、操舵（steer）、後続（followUp）の意味は sdk.md。

AGENTS.md：リポジトリのルールをすべてのモデルへ書く

Pi 起動時は ~/.pi/agent/AGENTS.md、親ディレクトリとカレントの AGENTS.md（または CLAUDE.md）を連結する。ある層に AGENTS.override.md があれば、その層は上書きファイルだけを読む。これが「モデルを換えてもルールは換えない」着地点だ。Claude、GPT、Gemini が同じ入口、テストコマンド、レッドラインを読む。システムプロンプトを置き換えるなら .pi/SYSTEM.md、追記なら APPEND_SYSTEM.md。

# このリポジトリが Pi に渡すルール
- パッケージ管理：npm。勝手に pnpm へ変えない。
- 検査：npm test && npm run lint
- レッドライン：.env、auth.json、*.pem をコミットしない
- デフォルトは読み取り専用。ユーザーが「ファイルを変更してよい」と明示したときだけ write/edit を使う

ヘッドレス CI はプロジェクト信頼ダイアログを出さない。保存済みの trust 決定が無いとき、非対話モードはグローバル defaultProjectTrust に従う。ask（デフォルト）と never はプロジェクト級 .pi/ 資源を無視し、always だけが信頼する。一回限りの上書きは --approve / --no-approve。自前 runner へ Pi を入れるなら、先に信頼ポリシーをマシンイメージへ書き、それからモデルを語る。GitHub Actions とクラウド Mac runner の分層は GitHub Actions macOS 自前ランナーとクラウド Mac。

シナリオ別の選び方

本当に問うべきは「Pi を入れるかどうか」ではなく、第一制約だ。対話でコードを直したいのか、Agent をスクリプトにしたいのか、一社公式 CLI の箱出し体験だけでよいのか。

「Cloud Mac がなぜ Agent の実行層なのか」というプロダクト判断は、なぜ Cloud Mac が 2026 年 iOS 開発の標準になったのか を参照。本記事が足すのはノード上の層：npm、鍵、モデル切替、TypeScript スクリプト。

推奨スタック

ツールの重ね使いは許容される。Pi が解くのは「差し替え可能なモデルの coding harness」。ふたを閉じても止まらない Mac を渡すわけでも、三社の請求を肩代わりするわけでもない。

• 個人の日常スタック：グローバル pi ＋ デフォルトの ANTHROPIC_API_KEY ＋ 予備の二本 ＋ リポジトリ AGENTS.md。対話では Ctrl+L でモデルを換える。ルールは換えない。
• TypeScript リポジトリスタック：グローバル CLI は人用。devDependencies に SDK をもう一式入れ、スクリプト用にする。レビューは読み取り専用ツール。ファイル改変は人手確認の別コマンド。
• CI スタック：pi -p または SDK スクリプト ＋ GitHub Actions Secrets ＋ 自前 macOS runner。信頼ポリシーは --approve で固定。ログに鍵を出さない。
• マルチプロバイダゲートウェイスタック：OpenRouter / Cloudflare AI Gateway の一本で複数モデルを叩き、切替は Pi の /model。各マシンへ三本の公式キーを散らしたくないチーム向き。
• 最小検証スタック：CLI だけ入れ、鍵は一本だけ export し、pi -p "カレントディレクトリの ts ファイルを列挙する" を走らせる。四拍（インストール→認証→一回のタスク→再現可能）が通ってから、二社目と SDK を足す。

マルチエージェント授業や IM 分身は Pi の主戦場ではない。編成とゲートウェイが要るなら OpenMAIC とマルチエージェント協働時代。Pi が向くのは「同じ読み・直し・実行のループを、バックエンドだけ換えて続ける」ことだ。

よくある誤解

• Pi を Claude Code の無料クローンだと思う。sub-agent と plan mode は意図して入っていない。欲しい機能は拡張か Package で足す。「コアが痩せすぎ」と嘆いて次の IDE を待つのではない。
• 三本の鍵を、git に入る同一 dotenv へ突っ込む。開発機は shell profile か 1Password。CI は Secrets。共有マシンは権限 0600 の auth.json。SDK runtime key はディスクに残らず、マシン認証の代わりにはならない。
• ブログのモデル ID を本番へ固定する。カタログは更新される。スクリプトは getAvailable() か --list-models を使い、安定した provider 接頭辞でフォールバックする。
• CI で Agent にデフォルトの write/edit を渡す。レビューと巡回は読み取り専用ホワイトリスト。ファイル改変は人手の門を別に開く。
• ヘッドレスなのに trust ダイアログが出ると期待する。先に defaultProjectTrust を置くか --approve を渡す。さもなくばプロジェクト級 Skills は読み込まれない。
• スリープするノートで長時間 SDK タスクを走らせる。セッションツリーは復帰できるが、bash がスリープで途中切断された副作用は自動ロールバックしない。長時間タスクは常時稼働ノードへ。

導入ステップ

1. 譲れない条件を書く：対話だけか、スクリプトだけか、両方か。初週から三社同時接続が必須か。CI にディスク書き込みを許すか。
2. CLI を入れ、一度空で動かして確認：npm install -g --ignore-scripts @earendil-works/pi-coding-agent、pi --version、PATH を確認。
3. 鍵は一本だけ繋ぐ：export または /login、pi -p "カレントディレクトリを列挙する"。検収は「再現可能」であり、「返信が長い」ではない。
4. 二社目、三社目を足す：OPENAI_API_KEY / GEMINI_API_KEY を補い、/model または --provider で同じプロンプトを各社へ走らせる。ルールが AGENTS.md から来て、モデルの気質から来ていないことを確認する。
5. SDK をリポジトリへ書く：プロジェクト依存 ＋ 読み取り専用の scripts/pi-review.ts 一本。ツールホワイトリストはコードへ固定する。
6. 実行環境を決める：手元の試用は可。CI と長時間タスクは常時稼働のクラウド Mac か自前 runner へ。ログはマスキング。鍵は成果物に入れない。
7. 拡張と観測を後から足す：plan mode / MCP / 権限ゲートが要るときだけ Package を入れる。先に使用量、失敗フォールバック、人手の割り込みを測り、それから能力を広げる。

FAQ

Pi Coding Agent と Claude Code の関係は？

Claude Code は Anthropic 公式の coding ワークフローで、モデルと入口が一体だ。Pi は第三者の最小 harness で、Anthropic 鍵や Claude サブスクも使えるし、OpenAI と Gemini を同時に繋げる。公式の深い統合を置き換えるものではない。置き換えるのは「モデルを換えるたびに道具一式を換える」ことだ。

Claude、GPT、Gemini を同時に設定しなければならない？

必須ではない。一本の鍵でインストール検収は通る。二社目の意味は、同じ AGENTS.md とツールホワイトリストのまま、タスクに応じてバックエンドを換えること。二社目の請求が無いなら、マルチモデルのために運用面を広げない。

グローバル npm インストールとプロジェクト内 SDK は衝突する？

同じコマンドを奪い合いはしない。ただしバージョンは漂う。約束はこうだ。人はグローバル CLI、スクリプトはプロジェクト package.json の版を固定。両方とも同じ ~/.pi/agent を読むときは、スクリプトの runtime key でマシン上の長期鍵を上書きしない。

Gemini の環境変数が GOOGLE_API_KEY ではない理由は？

公式表は Gemini API Key を GEMINI_API_KEY と書き、auth.json のキー名は google だ。Vertex は ADC とプロジェクト／リージョン変数を使い、AI Studio の Gemini 鍵とは別路。providers.md を基準にし、常識でキー名を当てない。

Windows / ヘッドレスのクラウド Mac に入れられる？

入れられる。npm グローバルパッケージはクロスプラットフォーム。公式には install.sh と PowerShell インストーラもある。ヘッドレス機は pi -p、RPC、SDK を使い、TUI に頼らない。OpenRouter 系 OAuth は SSH 上でコールバックを貼る。クラウド Mac では先に Node 版、PATH、auth.json 権限を固めるべきだ。

なぜクラウド Mac がまだ要る？手元の npm では足りない？

手元はコマンドを学ぶには足りる。夜間レビュー、ふたを閉じたあとの長時間修復、Xcode / 署名と同じ環境の CI には足りない。Pi はモデルを切り離したが、bash とファイルツールは、プロセスが走っているそのマシンにまだ縛られている。

まとめ

Pi Coding Agent の導入ガイドは、表面では npm、環境変数、三社のモデル ID だ。本当に着地させるのは分層である。harness とモデルを分ける。鍵とリポジトリを分ける。対話入口とスクリプト入口を分ける。2026年9月に耐える使い方は、グローバル CLI を人へ、SDK をリポジトリへ、AGENTS.md をすべてのバックエンドへ、常時稼働ノードを長時間タスクへ、だ。

非対称な結論は変わらない。分水嶺は Claude、GPT、Gemini のどれが強いかではなく、モデルを差し替え可能なバックエンドとして扱えるかどうかだ。先に一本の鍵で一回の pi -p を通し、それから二社目と TypeScript スクリプトを足す。実行面が要るなら、プロセスをスリープするノートからクラウド Mac へ移す。上げるべきは入口、認証、ノードであり、また次の IDE Agent ではない。