Piは、すでに通水・通电された毛布房のようなものです。住み心地は後からどう装飾するかで決まります。

インストール

方法一：Agentにインストールを任せる

既にCodex、Claude Code、あるいは他の端末操作可能なAgentを使用している場合は、以下の完全なテキストを渡してください：

現状のコンピュータ環境に基づきPi Coding Agentをインストール・検証してください：

1. 操作システム、CPUアーキテクチャ、Node.js、npm、および現在のPATHで有効なnodeとnpmを確認する；
2. Piの現在の要件はNode.js >= 22.19.0であり、不満足の場合はアップグレード方法を説明し、環境を直接変更しないこと；
3. 官方npmパッケージ@earendil-works/pi-coding-agentをインストールし、--ignore-scriptsを保持する；
4. インストール後、pi --versionとpi --helpで検証する；
5. APIキーやログイン認証情報を読み取らない、出力しない、変更しないこと；
6. /login経由での既存登録のログイン方法、および空白テストディレクトリでの只読み検証方法を教えてください；
7. 問題が発生した場合は、プロジェクトの公式リポジトリとウェブサイトの現在のドキュメントを確認し、パラメータを推測しないこと。

方法二：手動でインストールする

macOS、Linuxではターミナルを開き、WindowsではPowerShellを開き、次のコマンドを実行します：

node -v
npm -v

Piの公式npmパッケージのNode.js要件は以下の通りです：

>= 22.19.0

node -vの出力がこのバージョンより低い場合は、Node.jsをアップグレードする必要があります。nvm、Homebrew、システムNodeが複数インストールされている場合は、さらに注意が必要です：

which node
which npm

時には自分でアップグレードしたと考えていても、ターミナルが旧バージョンを呼び出している場合があります。これはCLIツールで非常に一般的な落とし穴です。

Windowsには追加要件があります。PiはデフォルトでGit Bashを介してBashコマンドを実行するため、Git for Windowsをインストールすれば問題ありません。

公式npmインストールコマンド：

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

注意点ですが、ここでの--ignore-scriptsは必ず保持する必要があります。これにより、依存関係のライフサイクルスクリプトがインストール時のライフサイクルで実行されないようになりますが、Piの通常のnpmインストールはこれらのスクリプトは必要ありません。

ウェブサイトでは以下の一括インストールスクリプトも提供されています：

curl -fsSL https://pi.dev/install.sh | sh

これらの方法はどれでも問題ありませんが、curl | shは確かに最も簡単です。

インストール後は検証します：

pi --version
pi --help

2026年9月12日時点で、公式リポジトリの現在のバージョンは0.85.1です。プロジェクトの進化は速く、バージョン番号が合っていなくてもインストール失敗とは限りません。まずGitHub Releasesとローカルのpi --versionを確認してください。

ウェブサイトのQuick startもこのnpmコマンドです。

最も一般的な状況の一つは、ターミナルが以下のメッセージを表示することです：

pi: command not found

まずターミナルを閉じて再開し、npmのグローバルインストール位置を確認してみましょう：

npm config get prefix
npm list -g --depth=0

リストに@earendil-works/pi-coding-agentが含まれている場合は、パッケージは概ねインストールされたものと考えられますが、npmのグローバル実行可能ディレクトリがPATHに含まれていない可能性があります。macOSとLinuxの場合はグローバル前缀のbinディレクトリを確認し、Windowsの場合はnpmのグローバルディレクトリを確認してください。

もう一つの問題は、Node.jsのバージョンは問題ないように見えても、Piを実行すると古い環境が使われている場合です。以下の項目を一緒に確認してみてください：

which node
which npm
which pi
node -v
pi --version

piが開けるがモデルリストが空の場合は、まず/loginを実行し、モデルを選択します。もしくは終了後コマンドラインで以下のコマンドを実行します：

pi --list-models

直接起動します：

pi

起動後、画面は比較的シンプルです：中央が入力欄で、下部には現在のディレクトリ、コンテキスト、モデルが表示されます。

端末画面に入ってから入力します：

/login

Piはモデルプロバイダを選択するよう求められます。公式では15社以上のモデルプロバイダをサポートしており、APIキーを通して走るだけでなく、既存の購読にログインすることも可能です。

ChatGPT PlusやProを持っている方は、OpenAI Codexを選択できます。GitHub Copilotもサポートされています。Claude Pro/Maxはログイン可能ですが、公式で特別な注意がつけられています。第三方Harnessの呼び出しはAnthropicのextra usageを通りますので、Tokenが追加で請求されるため、パッケージ内の許可量は直接消費されません。この点は注意が必要です。

DeepSeek APIを使っている方は、環境変数で以下のように設定することも可能です：

export DEEPSEEK_API_KEY=あなたのKey
pi

しかし初心者向けには、Pi内で/loginを使うことをおすすめします。証明情報は~/.pi/agent/auth.jsonに保存されます。

ログイン成功後、以下のコマンドでモデルを切り替えたり、思考レベルを調整したりできます：

/model
/thinking

Ctrl+Lでもモデル選択器を簡単に開け、Shift+Tabで思考レベルを切り替えることができます。

テスト用のプロジェクトディレクトリに入り、以下のコマンドを実行します：

pi --tools read,grep,find,ls -p "現在のディレクトリを読み取り、プロジェクトの目的、エントリーファイルの場所、実行すべきチェックを教えてください。ファイルを変更しないでください。"

ここではPiのPrintモードを使用し、タスク完了後は直接終了します。--toolsで使用可能なツールを読み取りの範囲に限定しています。モデルが接続できるか、Piがワークスペースを読み取れるか、ツールの制限が有効になっているかを三つの点を確認します。

もし特定のファイルだけを見たい場合は、以下のようにファイルを直接渡すことも可能です：

pi -p @README.md "このプロジェクトのインストールと起動方法を大ざっぱに説明してください"

Piは画像の確認もサポートしています：

pi -p @screenshot.png "このエラーページを見て、診断の順序を教えてください"

専用のテストディレクトリを作成します：

mkdir pi-playground
cd pi-playground
pi

以下の最小限のタスクを渡します：

まず現在の作業ディレクトリを確認し、既存のファイルを一覧表示する。
次にhello-pi.mdを作成し、内容を以下のようにする：現在の時間、作業ディレクトリ、使用可能なツール名。
hello-pi.md以外のファイルを作成、変更、削除しないこと。
完了後、ディレクトリを再確認し、実際に何が起きたかを教えてください。

このタスクは技術的には簡単ですが、検証には最適です。ディレクトリ読み取り、ファイル書き込み、制約遵守、結果検証が含まれます。

これらがすべて正常に動作することを確認した後、本格的なプロジェクトにPiを投入する準備が整います。

もしプロジェクトに.pi/settings.json、.piリソース、プロジェクトレベルのSkillsが含まれている場合は、Piから「現在のディレクトリを信頼しますか？」と尋ねられます。信頼することを選ぶと、プロジェクト設定、欠けているパッケージのインストール、プロジェクトExtensionの実行が可能になります。

• /login：モデルプロバイダのログイン・切り替え
• /model：モデル切り替え
• /thinking：思考レベルの調整
• /new：新規会話の開始
• /resume：過去の会話の続き
• /tree：会話木を開き、任意のノードにジャンプ
• /compact：コンテキストの手動圧縮
• /reload：設定、Skills、拡張機能、テーマの再読み込み
• /hotkeys：すべてのショートカットキーを表示
• /session：現在の会話ファイル、ID、Token、コストを表示

特に重要なのは/treeコマンドです。

普通のチャットで方向が間違えた場合、後ろからやり直すことになります。PiのSessionは木構造で保存されており、古いメッセージに戻ってから新しい分岐を伸ばすことができます。元の分岐は同じJSONLファイルに残ります。

例えばコードをリファクタリングさせようとして途中で方向が違うと、直前の「开始重构」の前まで戻って別の案に切り替えることができます。これにより前のコンテキストをすべて投げ直す必要がなくなり、特に長いタスクでは非常に便利です。

piの会話はデフォルトで以下の場所に保存されます：

~/.pi/agent/sessions/

コマンドラインからは以下のように会話を続けることも可能です：

pi -c
pi -r

前者は最近の会話を続け、後者は過去の会話から選択できます。

Piは端末でのチャットだけでなく、様々な使用方法があります。

公式では使用方法を4つのグループに分類しています：Interactive、Print/JSON、RPC、SDK。PrintとJSONはプログラム化された一時的なまたはストリーミングタスクに適しており、同一グループにまとめられています。

デフォルトでpiを実行するとInteractiveモードに入り、日常のコード作成や長いタスクに適しています。

Printモードは一度だけのコマンドに適しています：

pi -p "このプロジェクトに明らかな問題がいくつあるかチェックしてください"

JSONモードはイベントストリームを連続的に出力し、シェルスクリプト、ログシステム、または自分の自動化プログラムに接続しやすくなります：

pi --mode json "現在のプロジェクトを分析してください"

RPCモードは標準入出力を通じてJSONLを受け取ります。Piを非Node.jsアプリケーションに埋め込むのに適しています：

pi --mode rpc

PiにはSDKもあります。開発者はTypeScriptプロジェクトでAgent Sessionを作成し、Piを自身のAgent Runtimeとして使用できます。

したがって、見たのは同一の核ですが、端末、スクリプト、サービス、自分の製品で使えるようになっています。

三个官方案例

以下の三つのケースはPiの公式公開ページから採用しました。Piのハarnessがどのように使用されるかをより明確に理解するために。

ケース一：木構造の会話

先ほど説明したように、Piの会話は単一のチャットストリームだけではありません。公式共有会話ページの左側には241個のノードと異なる分岐が表示され、右側にはSystem Prompt、ツール、メッセージ、呼び出し記録が展開されます。

これは「履歴記録をサポートする」というより具体的で実用的な機能です。古いノードに戻って別の道を切り替えたり、全体のプロセスをエクスポートしたりできます。

ケース二：他のExtension、Skills、テーマを直接導入

PiのウェブサイトにはPackage Catalogがあります。5,435個の項目が含まれ、MCP Adapter、ウェブアクセスからワークフロー、データベース、タスクコンポーネントまであります。

これらはpi install npm:<package>で直接本機にインストール可能な機能パッケージです。つまりPiの拡張エコシステムは非常に豊富です。

ケース三：Doomを端末に埋め込む

このケースは非常に奇抜ですが、Extensionがどの程度まで機能を拡張できるかを示しています。公式デモでは、Agentがバックグラウンドでタスクを実行し、DoomがPiのTUIに直接埋め込まれている様子！この実装は本当に素晴らしいです。下部にはモデル、Token、コスト、タスク状態も残されています。

Extensionはイベントを受け取る、UIを変更する、新しいツールを登録する、さらにはインタラクション層全体を交換するまで機能します。

あなたの既存のCodex、Claude Skillsを接続する

Piは自動的に以下の場所をスキャンします：

~/.pi/agent/skills/
~/.agents/skills/
.pi/skills/
.agents/skills/

プロジェクトレベルのSkillsは、プロジェクトが信頼された後のみ読み込まれます。

既にClaude SkillsやCodex Skillsを多く持っている方は、グローバル設定を編集してください：

~/.pi/agent/settings.json

以下を追加します：

{
  "skills": [
    "~/.claude/skills",
    "~/.codex/skills"
  ]
}

Pi内で以下のコマンドを実行します：

/reload

Skillsは段階的にロードされます。起動時は名前と説明だけをコンテキストに入れるが、タスクマッチング後に完全なSKILL.mdを読み込み、すべての説明をコンテキストに一気に詰め込むことはありません。

特定のSkillsを強制呼び出したい場合は、以下のように入力します：

/skill:skill-name

この設計は現在のAgent Skillsの標準と整合しています。過去にCodex、Claude Codeで作成した多くのSkills能力パッケージも再利用可能です。

Piの機能を拡張する

Skillsは「どうするか」を解決し、ExtensionsはPi自体を直接変更し、機能がより強力です。

Extensionは新しいツール、新しいコマンド、新しいショートカットキー、イベントの登録が可能です。状態バー、エディタ、ポップアップ、テーマの変更も可能です。子Agent、計画モード、権限ゲート、Git自動コミット、SSH実行、サンドボックス、MCPの補完なども可能です。

公式ホームページで示されたDoomは、非常に直感的なExtensionの例です。

公式の推奨：何か能力が足りない場合は、Piに自分でExtensionを作成する。変更後は/reloadを実行し、現在の作業を続けます。

もしこの能力を後で再利用したい場合は、Extension、Skills、Prompt、テーマをすべてPi Packageにまとめてインストールできます：

pi install npm:@foo/pi-tools
pi install git:github.com/user/repo
pi list
pi config

説明しておきますが、Pi Packageはブラウザの隔離プラグインとは全く異なります。

Piは、いくつかのデスクトップAgentのようにファイル削除、コマンド実行前に確認ボックスを表示しません。起動プロセスのファイル、ネットワーク、認証、システム権限をそのまま継承します。

しかしこれは隠れたバグではなく、公式ホームページでは「No permission popups」と明記されています。

端末操作に慣れている人にとっては、このYoloモードはタスクが頻繁に中断されません。

しかし初心者にとっては、Promptが不適切な場合、AgentがCドライブを空にするような悪行をしてしまう可能性もあります。。。

初心者初回使用時は以下の点に注意が必要です：

• まず空白ディレクトリから始め、デスクトップ、ドキュメント、またはホームディレクトリ全体を開かないこと；
• コード読み込み時は--tools read,grep,find,lsで只読みモードにする；
• ~/.pi/agent/auth.json、.env、他の認証ファイルを読み取らせないこと；
• 第三方PackageとExtensionはソースコードを審査し、インストールする；
• 長時間自動実行させる場合はDocker、OpenShellなど別の沙箱に投入する。

公式では様々な隔離方案を提供しています。最も簡単なのはPi全体をDockerに投入することです。

注意点として、投入されたワークディレクトリは宿主機に書き戻せることに注意してください。~/.pi/agentも投入すれば、認証と会話ファイルもコンテナに漏洩する可能性があります。

また、Piは起動時に新バージョンをチェックし、初回インストールまたはアップグレード検出時に匿名のバージョン情報を送信します。インストールテlemetryを気にする場合は、設定で無効にしたり、以下のように実行する：

PI_TELEMETRY=0 pi

完全にネットワークチェックを無効にする場合は：

PI_OFFLINE=1 pi

Piが適した人

単に一つの製品をダウンロードし、ログインし、安全なガードレールの中で安定して使用するだけなら、Piは最も簡単な選択肢ではありません。多くの「装好ていればあるべき」機能を省いており、多くのものを自分で用意する必要があります。

複数のモデルを使用し、多くのSkillsを持ち、Agentをスクリプトや製品に接続したい、端末と権限について基本的な判断ができる人、特に一人会社や独立開発者の方は、Piの価値をより感じやすくなります。

もちろん自由度が高いほど、セキュリティ面で自分でしっかりと守る必要があります。