Pi Agent マルチプラットフォームデプロイ

Pi Agent は Windows、macOS、Linux、Android(Termux)で動作します。

この章では各プラットフォームの設定のポイントを説明します。


macOS 設定

macOS は Pi Agent のファーストクラスサポートプラットフォームであり、ほとんどの機能がすぐに使えます。

推奨ターミナル

ターミナルインストール方法推奨理由
iTerm2brew install --cask iterm2ネイティブ True Color サポート、画像表示が良好、機能が豊富
Kittybrew install --cask kittyGPU アクセラレーションレンダリングで高速
Warpbrew 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+VCtrl+V
複数行入力Ctrl+EnterShift+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 内で以下のコマンドを実行してください。

例

# 1. パッケージを更新し、Node.js と termux-api コマンドラインツールをインストール
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 に次を追加します:

例

# ファイルパス: ~/.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、または同等のシェル設定ファイルに追加できます:

例

# ファイルパス:~/.zshrc(bash ユーザーは ~/.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
その他の拡張