Pi Agent Multi-platform Deployment
Pi Agent supports running on Windows, macOS, Linux, and Android (Termux).
This chapter covers the configuration essentials for each platform.
macOS Configuration
macOS is a first-class supported platform for Pi Agent, and most features work out of the box.
Recommended Terminals
| Terminal | Installation Method | Reason for Recommendation |
|---|---|---|
| iTerm2 | brew install --cask iterm2 | Native True Color support, good image rendering, rich features |
| Kitty | brew install --cask kitty | GPU-accelerated rendering, fast |
| Warp | brew install --cask warp | Modern terminal, integrated AI features |
Verify True Color Support
$ echo $COLORTERM truecolor
Shell Aliases
Pi Agent runs bash in non-interactive mode (i.e.,bash -c) by default, it does not automatically expand your Shell aliases.
Core mechanism: letting Pi recognize Shell aliases. To use custom aliases in Pi, write the following configuration to ~/.pi/agent/settings.json (or ~/.atomic/agent/settings.json) so that it actively loads your Shell configuration file (such as ~/.zshrc or ~/.bashrc) at startup:
{
"shellCommandPrefix": "shopt -s expand_aliases\neval \"$(grep '^alias ' ~/.zshrc)\""
}Note:Please change the path ~/.zshrc to the actual path of your Shell configuration file.
Windows Configuration
On Windows, you can run Pi Agent through a native terminal or WSL2. The key is choosing the right terminal and resolving shortcut conflicts.
Recommended Installation Method
On Windows, it is recommended to useWindows Terminalwith WSL2, or directly use Node.js.
Install Git for Windows
Pi uses Git Bash by default to execute commands on Windows.
At startup, it searches in order, including the default pathC:\Program Files\Git\bin\bash.exe。
If Git for Windows is not installed, bash will not be found at startup; simply install Git for Windows to resolve this.
If you don't want to use Git Bash, you can alsoshellPathconfigure a different bash, or throughdefaultToolsswitch to the PowerShell tool.
Install Node.js
fromnodejs.orgDownload the installer, or use winget:
# PowerShell > winget install OpenJS.NodeJS.LTS
Install Pi Agent
Run the following in PowerShell or CMD within Windows Terminal:
# PowerShell > npm install -g --ignore-scripts @earendil-works/pi-coding-agent
Windows-specific Shortcuts
| Function | Windows Shortcut | macOS/Linux Shortcut |
|---|---|---|
| Paste image | Alt+V | Ctrl+V |
| Multiline input | Ctrl+Enter | Shift+Enter |
| Send follow-up message | Ctrl+Q (send), Alt+Q (retrieve) | Alt+Enter |
On Windows, Ctrl+Q sends follow-up messages and Alt+Q retrieves queued messages by default; no remapping is needed.
Configuration is only needed if you want to switch to Alt+Enter.
In Windows Terminal, Alt+Enter defaults to the fullscreen shortcut.
If you want Pi Agent to receive this shortcut, you need to remove or remap the fullscreen shortcut in Windows Terminal settings.
Search for "toggleFullscreen" in settings and change its shortcut to another combination.
Then set pi'sapp.message.followUpbinding to alt+enter.
Suspend Behavior
Windows native terminals do not support Unix job control.
On native Windows, Ctrl+Z is bound to undo editing; you need to bind your own shortcut for suspension.
Under WSL, use Alt+Z to suspend; Ctrl+Z can still suspend processes, and fg can bring them back to normal.
Termux (Android) Configuration
Pi Agent can run on Android devices via Termux.
Installation Steps
First install Termux itself. Get the latest installer package from F-Droid, then run the following commands in Termux.
Example
pkg update && pkg upgrade
pkg install nodejs termux-api
# 2. Install Pi Agent
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
# 3. Verify installation
pi --version
# 4. Before using shared storage for the first time, run it once to grant access to paths such as the Downloads directory
termux-setup-storage
In addition to Termux itself, you also need to install the Termux:API app on your phone.
This app can also be obtained from F-Droid; device integration capabilities such as clipboard depend on it.
If you only install the termux-api command-line package without installing the Termux:API app, the related commands will not take effect.
Notes
The Termux environment differs from regular Linux; please be aware of the following points.
| Item | Description |
|---|---|
| Storage path | Termux's storage access path differs from regular Linux; use ~/storage/shared/ to access shared storage, and run termux-setup-storage before first use. |
| Image display | Image display may be limited on some terminals |
| Clipboard | Termux clipboard integration only supports text; image pasting is not available |
| Input experience | It is recommended to use a Bluetooth keyboard or OTG keyboard for a better editing experience |
tmux Integration
Pi Agent works normally in tmux sessions.
Advantages
Putting Pi Agent into tmux is mainly for persistence and multi-window capabilities.
| Advantage | Description |
|---|---|
| Session persistence | Even if SSH disconnects, Pi Agent keeps running in the background |
| Multi-window layout | Run Pi Agent in one window, and view code in another |
| Remote development | Use Pi Agent after SSHing into a server |
Recommended Configuration
Add the following to ~/.tmux.conf:
Example
# Ensure True Color support
set -g default-terminal "tmux-256color"
set -ag terminal-overrides ",*:Tc"
# Enable extended key reporting and forward key combinations in CSI-u format
# Without these two lines, Shift+Enter in tmux degrades to a plain Enter
set -g extended-keys on
set -g extended-keys-format csi-u
# Increase scrollback buffer (useful when viewing large AI outputs)
set -g history-limit 50000
Among these, the two extended-keys lines are the key configuration; they ensure that key combinations such as Shift+Enter and Ctrl+Enter are correctly passed to pi.
extended-keys-format csi-u requires tmux 3.5 or higher; you can usetmux -Vto check the version.
$ tmux -V tmux 3.5a
Without these two lines, Shift+Enter in tmux degrades to a plain Enter, and multiline input will send the message directly.
If the tmux version is between 3.2 and 3.4, omit the csi-u line; pi still supports tmux's default xterm format.
Terminal Settings Optimization
Regardless of which terminal you use, the following settings will directly affect Pi Agent's display quality.
| Setting | Recommended Value | Description |
|---|---|---|
| True Color | Enable | Ensure the terminal supports 24-bit color |
| Font | Monospaced font (e.g., JetBrains Mono, Fira Code) | Ensure code alignment and special character display |
| Scrollback buffer | At least 10000 lines | View large amounts of AI output and historical messages |
| VS Code Terminal | Set minimumContrastRatio to 1 | Ensure theme colors render accurately |
VS Code Integrated Terminal Configuration
Add the following configuration to VS Code's settings.json; the file path is~/Library/Application Support/Code/User/settings.json（macOS）：
Example
"terminal.integrated.minimumContrastRatio": 1,
"terminal.integrated.fontFamily": "JetBrains Mono",
"terminal.integrated.fontSize": 13
}
Shell Alias Recommendations
The following is a complete set of Pi Agent aliases, compatible across platforms. You can add them to ~/.zshrc, ~/.bashrc, or an equivalent shell configuration file:
Example
# Common Pi Agent aliases
alias pin='pi --name' # Start a named session
alias pic='pi -c' # Continue the most recent session
alias pir='pi -r' # Resume a historical session
alias piq='pi -p' # Quick one-off Q&A
alias pip='pi --print' # Print mode (same as -p)
alias pif='pi --fork' # Fork a session
alias pii='pi --no-session' # Temporary mode (not saved)
alias piro='pi --tools read,grep,find,ls' # Read-only mode
alias pirev='pi -p "Review staged code changes (git diff --cached)"'
If you use fish shell, change alias to abbr or use fish's alias syntax.
# fish shell 使用 abbr 定义缩写 abbr -a pic pi -cOther Extensions