Pi Agent マルチプラットフォームデプロイ
Pi Agent は Windows、macOS、Linux、Android(Termux)で動作します。
この章では各プラットフォームの設定のポイントを説明します。
macOS 設定
macOS は Pi Agent のファーストクラスサポートプラットフォームであり、ほとんどの機能がすぐに使えます。
推奨ターミナル
| ターミナル | インストール方法 | 推奨理由 |
|---|---|---|
| iTerm2 | brew install --cask iterm2 | ネイティブ True Color サポート、画像表示が良好、機能が豊富 |
| Kitty | brew install --cask kitty | GPU アクセラレーションレンダリングで高速 |
| Warp | brew install --cask warp | モダンなターミナル、AI 機能の統合 |
True Color サポートの確認
$ echo $COLORTERM truecolor
シェルエイリアス
Pi Agent は非対話モードで bash を実行するとき(つまりbash -c)のとき、デフォルトではシェルエイリアスを自動展開しません。
コアメカニズム:Pi にシェルエイリアスを認識させる。Pi でカスタムエイリアスを使用するには、以下の設定を ~/.pi/agent/settings.json(または ~/.atomic/agent/settings.json)に書き込み、起動時にシェル設定ファイル(例:~/.zshrc や ~/.bashrc)を明示的に読み込ませる必要があります:
{
"shellCommandPrefix": "shopt -s expand_aliases\neval \"$(grep '^alias ' ~/.zshrc)\""
}注意:パス ~/.zshrc は、実際に使用しているシェル設定ファイルのパスに変更してください。
Windows 設定
Windows ではネイティブターミナルまたは WSL2 で Pi Agent を実行できます。重要なのはターミナルを正しく選び、ショートカットキーの競合を処理することです。
推奨インストール方法
Windows では次を使用することを推奨します:Windows TerminalWSL2 と組み合わせるか、直接 Node.js を使用します。
Git for Windows のインストール
Pi は Windows 上でデフォルトで Git Bash を使用してコマンドを実行します。
起動時には順番に検索され、その中にはデフォルトのパスも含まれます。C:\Program Files\Git\bin\bash.exe。
Git for Windows をインストールしていない場合、起動時に bash が見つからないため、Git for Windows を直接インストールすれば解決します。
Git Bash を使用したくない場合は、次のようにしてshellPath設定で他の bash を指定するか、次を使用してdefaultToolsPowerShell ツールに変更できます。
Node.js のインストール
からnodejs.orgインストーラーをダウンロードするか、winget を使用します:
# PowerShell > winget install OpenJS.NodeJS.LTS
Pi Agent のインストール
Windows Terminal の PowerShell または CMD で実行します:
# PowerShell > npm install -g --ignore-scripts @earendil-works/pi-coding-agent
Windows 固有のショートカットキー
| 機能 | Windows ショートカットキー | macOS/Linux ショートカットキー |
|---|---|---|
| 画像の貼り付け | Alt+V | Ctrl+V |
| 複数行入力 | Ctrl+Enter | Shift+Enter |
| フォローアップメッセージの送信 | Ctrl+Q(送信)、Alt+Q(取得) | Alt+Enter |
Windows ではデフォルトで、Ctrl+Q がフォローアップメッセージの送信、Alt+Q が待機メッセージの取得に使用され、再マッピングは不要です。
Alt+Enter に変更したい場合のみ設定が必要です。
Windows Terminal では、Alt+Enter はデフォルトで全画面ショートカットキーです。
Pi Agent にこのショートカットキーを受け取らせるには、Windows Terminal の設定で全画面ショートカットキーを削除または再マッピングする必要があります。
設定で "toggleFullscreen" を検索し、そのショートカットキーを別の組み合わせに変更してください。
次に pi のapp.message.followUpを alt+enter にバインドします。
サスペンド動作
Windows ネイティブターミナルは Unix のジョブ制御をサポートしていません。
ネイティブ Windows では Ctrl+Z は編集の取り消しにバインドされているため、サスペンドには自分でショートカットキーをバインドする必要があります。
WSL では Alt+Z でサスペンドでき、Ctrl+Z でもプロセスをサスペンドできます。fg と併用することで通常に復帰して使用できます。
Termux(Android)設定
Pi Agent は Android デバイス上で Termux を通じて実行できます。
インストール手順
まず Termux 本体をインストールします。F-Droid から最新版のインストールパッケージを入手し、Termux 内で以下のコマンドを実行してください。
例
pkg update && pkg upgrade
pkg install nodejs termux-api
# 2. Pi Agent をインストール
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
# 3. インストールの確認
pi --version
# 4. 共有ストレージを最初に使用する前に一度実行して、ダウンロードディレクトリなどのパスへのアクセスを許可する
termux-setup-storage
Termux 本体に加えて、スマートフォンに Termux:API アプリをインストールする必要があります。
このアプリも F-Droid から入手できます。クリップボードなどのデバイス統合機能はこれに依存しています。
termux-api コマンドラインパッケージだけをインストールして Termux:API アプリをインストールしない場合、関連コマンドは機能しません。
注意事項
Termux 環境は通常の Linux とは異なります。以下の点に注意してください。
| 項目 | 説明 |
|---|---|
| ストレージパス | Termux のストレージアクセスパスは通常の Linux とは異なり、共有ストレージへのアクセスには ~/storage/shared/ を使用します。初回使用前に termux-setup-storage を実行してください。 |
| 画像表示 | 一部のターミナルでは画像表示機能が制限される場合があります |
| クリップボード | Termux のクリップボード統合はテキストのみをサポートしており、画像の貼り付けは使用できません |
| 入力体験 | より良い編集体験のために、Bluetooth キーボードまたは OTG キーボードの使用を推奨します |
tmux 統合
Pi Agent は tmux セッション内で正常に動作します。
利点
Pi Agent を tmux 内で実行する主な目的は、永続化と複数ウィンドウの機能を得ることです。
| 利点 | 説明 |
|---|---|
| セッションの永続化 | SSH が切断されても、Pi Agent はバックグラウンドで実行され続けます |
| 複数ウィンドウのレイアウト | 1つのウィンドウで Pi Agent を実行し、別のウィンドウでコードを表示する |
| リモート開発 | サーバーに SSH 接続後に Pi Agent を使用する |
推奨設定
~/.tmux.conf に次を追加します:
例
# True Color サポートを有効にする
set -g default-terminal "tmux-256color"
set -ag terminal-overrides ",*:Tc"
# 拡張キー報告を有効にし、CSI-u 形式でコンビネーションキーを転送する
# この2行がないと、tmux 内で Shift+Enter が通常の Enter に退化します
set -g extended-keys on
set -g extended-keys-format csi-u
# スクロールバックバッファを増やす(大量の AI 出力を表示するときに便利)
set -g history-limit 50000
このうち extended-keys の2行が重要です。Shift+Enter、Ctrl+Enter などのコンビネーションキーを pi に正しく渡すための設定です。
extended-keys-format csi-u は tmux 3.5 以降が必要です。次を使用してtmux -Vバージョンを確認できます。
$ tmux -V tmux 3.5a
この2行を追加しない場合、tmux 内で Shift+Enter が通常の Enter に退化し、複数行入力ではメッセージがそのまま送信されてしまいます。
tmux のバージョンが 3.2 から 3.4 の間の場合は、csi-u の行を省略してください。pi は引き続き tmux デフォルトの xterm フォーマットをサポートします。
ターミナル設定の最適化
どの端末を使用する場合でも、以下の設定は Pi Agent の表示効果に直接影響します。
| 設定項目 | 推奨値 | 説明 |
|---|---|---|
| True Color | 有効 | 端末が24ビットカラーをサポートしていることを確認する |
| フォント | 等幅フォント(JetBrains Mono、Fira Code など) | コードの整列と特殊文字の表示を確実にする |
| スクロールバッファ | 最低10000行 | 大量の AI 出力と履歴メッセージを表示する |
| VS Code ターミナル | minimumContrastRatio を 1 に設定する | テーマの色が正確にレンダリングされることを確認する |
VS Code 統合ターミナル設定
VS Code の settings.json に以下の設定を追加します。ファイルパスは~/Library/Application Support/Code/User/settings.json(macOS):
例
"terminal.integrated.minimumContrastRatio": 1,
"terminal.integrated.fontFamily": "JetBrains Mono",
"terminal.integrated.fontSize": 13
}
シェルエイリアスの推奨
以下は、Pi Agent の完全なエイリアス一式です。各プラットフォームで共通で、~/.zshrc、~/.bashrc、または同等のシェル設定ファイルに追加できます:
例
# Pi Agent よく使うエイリアス
alias pin='pi --name' # 名前付きセッションの起動
alias pic='pi -c' # 最近のセッションを続行
alias pir='pi -r' # 履歴セッションを復元
alias piq='pi -p' # クイック単発 Q&A
alias pip='pi --print' # Print モード(-p と同じ)
alias pif='pi --fork' # セッションをフォーク
alias pii='pi --no-session' # 一時モード(保存しない)
alias piro='pi --tools read,grep,find,ls' # 読み取り専用モード
alias pirev='pi -p "ステージング済みのコード変更をレビュー(git diff --cached)"'
fish shell を使用している場合は、alias を abbr に変更するか、fish の alias 構文を使用してください。
# fish shell 使用 abbr 定义缩写 abbr -a pic pi -cその他の拡張