@earendil-works/pi-coding-agent 0.86.1 → 0.87.1

package/docs/terminal-setup.md

@@ -1,73 +1,74 @@
-# Terminal Setup
+# Configure your terminal
 
-Pi uses the [Kitty keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/) for reliable modifier key detection. Most modern terminals support this protocol, but some require configuration.
+Most modern terminals work with Pi without additional setup. Use this page when modified keys, scrolling, links, images, colors, or input-method editor (IME) positioning do not behave as expected.
 
-## Capability Overrides
+Pi uses extended-key protocols so terminals can distinguish combinations such as `Shift+Enter` and `Alt+Enter` from plain `Enter`. Terminal proxies, multiplexers, and built-in IDE terminals can change or discard that information.
 
-Pi auto-detects OSC 8 hyperlinks, inline image protocols, and truecolor. If detection fails behind a terminal proxy or multiplexer, use these advanced overrides:
+## Troubleshooting
 
-| Capability | Environment variable | JSON setting |
-|------------|----------------------|--------------|
-| OSC 8 hyperlinks | `PI_HYPERLINKS=1\|0\|auto` | `terminal.hyperlinks: true\|false\|"auto"` |
-| Inline images | `PI_IMAGE_PROTOCOL=kitty\|iterm2\|none\|auto` | `terminal.images: "kitty"\|"iterm2"\|false\|"auto"` |
-| Truecolor | `PI_TRUE_COLOR=1\|0\|auto` | `terminal.trueColor: true\|false\|"auto"` |
+| Symptom | Start here |
+|---|---|
+| `Shift+Enter` submits instead of inserting a line | Your terminal's section below; for tmux, see [Run Pi in tmux](tmux.md) |
+| `Alt+Enter` does not queue a follow-up | [WezTerm](#wezterm), [Alacritty](#alacritty), or [Windows Terminal](#windows-terminal) |
+| Fullscreen scrolling is unusually slow | [iTerm2](#iterm2) |
+| Links work but show no hover preview | [Ghostty](#ghostty) |
+| Inline images or colors are not detected | [Override detected capabilities](#override-detected-capabilities) |
+| An IME candidate window appears in the wrong place | [WezTerm](#wezterm) or [IntelliJ IDEA](#intellij-idea-integrated-terminal) |
+| Modified keys fail only inside tmux | [Run Pi in tmux](tmux.md) |
 
-Settings take precedence over environment variables; unset or `auto` preserves detection. Only force capabilities supported by the complete terminal path, since unsupported escape sequences can corrupt rendering.
+Use `/hotkeys` to inspect Pi's active shortcuts. See [Keybindings](keybindings.md) to change them.
 
 ## Kitty
 
-Works out of the box.
+Kitty supports the required keyboard protocol without additional configuration.
 
 ## iTerm2
 
-### Regular TUI mode
-
-Works out of the box.
+Regular terminal mode works without additional configuration.
 
-### Fullscreen TUI mode
+### Fix slow fullscreen scrolling
 
-Pi owns the viewport, so iTerm2 sends mouse-wheel reports instead of scrolling its native scrollback. With iTerm2's default fast-trackpad behavior, those reports can lose most of an accelerated wheel delta, making fullscreen scrolling much slower than regular scrolling.
+In fullscreen mode, Pi owns the viewport, so iTerm2 sends mouse-wheel reports instead of scrolling native terminal history. Fast trackpad gestures can then move only about one line at a time.
 
-If fast mouse-wheel gestures move only about one line at a time in fullscreen mode:
+To change this behavior:
 
-1. Open **iTerm2 → Settings → Advanced**.
-2. Search for **Trackpad scrolls fast?** and set it to **No**.
+1. Open **iTerm2 > Settings > Advanced**.
+2. Search for **Trackpad scrolls fast?**.
+3. Set it to **No**.
 
-This is an iTerm2-wide workaround and may also change native trackpad scrolling. The underlying behavior is tracked in [iTerm2 issue 9619](https://gitlab.com/gnachman/iterm2/-/work_items/9619).
+This is an iTerm2-wide setting and can also change native trackpad scrolling. The underlying behavior is tracked in [iTerm2 issue 9619](https://gitlab.com/gnachman/iterm2/-/work_items/9619).
 
 ## Apple Terminal
 
-Pi enables enhanced key reporting when available. If Terminal.app still sends plain Return for `Shift+Enter`, pi uses a local macOS modifier fallback to treat that Return as `Shift+Enter`.
+Pi enables enhanced key reporting when available. If Terminal.app still sends plain Return for `Shift+Enter`, Pi uses a local macOS modifier fallback and treats it as `Shift+Enter`.
 
-This fallback only works when pi runs on the same Mac as Terminal.app. It cannot detect the local keyboard over remote SSH.
+The fallback works only when Pi runs on the same Mac as Terminal.app. It cannot inspect the local modifier state when Pi runs on another machine over SSH.
 
 ## Ghostty
 
-Add to your Ghostty config (`~/Library/Application Support/com.mitchellh.ghostty/config` on macOS, `~/.config/ghostty/config` on Linux):
+Add this mapping to Ghostty's configuration if `Alt+Backspace` does not work:
 
-```
+```text
 keybind = alt+backspace=text:\x1b\x7f
 ```
 
-Older Claude Code versions may have added this Ghostty mapping:
+The configuration file is `~/Library/Application Support/com.mitchellh.ghostty/config` on macOS and `~/.config/ghostty/config` on Linux.
 
-```
+Older Claude Code configurations may contain:
+
+```text
 keybind = shift+enter=text:\n
 ```
 
-That mapping sends a raw linefeed byte. Inside pi, that is indistinguishable from `Ctrl+J`, so tmux and pi no longer see a real `shift+enter` key event.
-
-If Claude Code 2.x or newer is the only reason you added that mapping, you can remove it, unless you want to use Claude Code in tmux, where it still requires that Ghostty mapping.
-
-Pi binds `Ctrl+J` as a default newline alias, so `Shift+Enter` keeps working in tmux via that remap without extra pi configuration.
+This sends a raw linefeed, which Pi cannot distinguish from `Ctrl+J`. Remove the mapping if an older Claude Code installation is the only reason you added it. Pi already binds `Ctrl+J` as a newline alternative, so the mapping may appear to work while still preventing Pi and tmux from receiving a real `Shift+Enter` event.
 
-### Fullscreen TUI mode
+### Open links in fullscreen mode
 
-In fullscreen mode, links remain clickable, but Ghostty does not show its hover underline or lower-left URL preview while pi captures mouse input. Hold `Shift+Command` on macOS or `Shift+Ctrl` on Linux to use Ghostty's native link handling.
+Links remain clickable in fullscreen mode, but Ghostty does not show its normal hover underline or URL preview while Pi captures mouse input. Hold `Shift+Command` on macOS or `Shift+Ctrl` on Linux to use Ghostty's native link handling.
 
 ## WezTerm
 
-WezTerm usually works out of the box for `Shift+Enter` via xterm modifyOtherKeys. To use the Kitty keyboard protocol explicitly, create `~/.wezterm.lua`:
+WezTerm normally reports `Shift+Enter` through xterm extended keys. To enable the Kitty keyboard protocol explicitly, create `~/.wezterm.lua`:
 
 ```lua
 local wezterm = require 'wezterm'
@@ -76,7 +77,19 @@ config.enable_kitty_keyboard = true
 return config
 ```
 
-On macOS, WezTerm binds `Option+Enter` to fullscreen by default. To use `Option+Enter` for pi follow-up queueing, add this key override:
+### Forward Alt+Enter on macOS
+
+WezTerm binds `Option+Enter` to fullscreen by default on macOS. To use it for Pi's follow-up queue, add this entry to your `config.keys` table:
+
+```lua
+{
+  key = 'Enter',
+  mods = 'ALT',
+  action = wezterm.action.SendString('\x1b[13;3u'),
+}
+```
+
+A complete minimal configuration is:
 
 ```lua
 local wezterm = require 'wezterm'
@@ -91,13 +104,20 @@ config.keys = {
 return config
 ```
 
-If you already have a `config.keys` table, add the entry to it.
+### Position an IME candidate window in WSL
 
-On WSL, WezTerm may require a visible hardware cursor for IME candidate window positioning. If CJK IME candidates do not follow the text cursor, set `PI_HARDWARE_CURSOR=1` before running pi or set `showHardwareCursor` to `true` in settings.
+If CJK IME candidates do not follow Pi's text cursor in WSL, show the hardware cursor:
+
+```bash
+export PI_HARDWARE_CURSOR=1
+pi
+```
+
+You can instead set `showHardwareCursor` to `true` in Pi settings.
 
 ## Alacritty
 
-Alacritty usually works out of the box for `Shift+Enter`. On macOS, `Option+Enter` may arrive as plain `Enter`. To use `Option+Enter` for pi follow-up queueing, add to `~/.config/alacritty/alacritty.toml`:
+Alacritty normally reports `Shift+Enter`. On macOS, `Option+Enter` can arrive as plain `Enter`. Add this to `~/.config/alacritty/alacritty.toml` to forward it to Pi:
 
 ```toml
 [[keyboard.bindings]]
@@ -106,20 +126,13 @@ mods = "Alt"
 chars = "\u001b[13;3u"
 ```
 
-Restart Alacritty after changing the config.
-
-## VS Code (Integrated Terminal)
+Restart Alacritty after changing the file.
 
-VS Code 1.109.5 and newer enable Kitty keyboard protocol in the integrated terminal by default, so `Shift+Enter` should work out of the box.
+## VS Code integrated terminal
 
-VS Code versions older than 1.109.5 need an explicit terminal keybinding for `Shift+Enter`.
+VS Code 1.109.5 and newer enable the Kitty keyboard protocol in the integrated terminal by default.
 
-`keybindings.json` locations:
-- macOS: `~/Library/Application Support/Code/User/keybindings.json`
-- Linux: `~/.config/Code/User/keybindings.json`
-- Windows: `%APPDATA%\\Code\\User\\keybindings.json`
-
-Add to `keybindings.json`:
+For an older version, add a `Shift+Enter` terminal binding to `keybindings.json`:
 
 ```json
 {
@@ -130,9 +143,15 @@ Add to `keybindings.json`:
 }
 ```
 
-## Zed (Integrated Terminal)
+The user `keybindings.json` file is normally located at:
+
+- macOS: `~/Library/Application Support/Code/User/keybindings.json`
+- Linux: `~/.config/Code/User/keybindings.json`
+- Windows: `%APPDATA%\\Code\\User\\keybindings.json`
 
-Add these key bindings to your Zed `keymap.json`:
+## Zed integrated terminal
+
+Add these bindings to Zed's `keymap.json`:
 
 ```json
 {
@@ -147,46 +166,54 @@ Add these key bindings to your Zed `keymap.json`:
 
 ## Windows Terminal
 
-Pi uses Windows-style keybindings when running natively on Windows or in WSL:
+Windows Terminal uses Pi's Windows and WSL shortcut defaults. See [Keybindings](keybindings.md) for the complete list.
 
-- `Alt+V` pastes an image or clipboard text.
-- `Ctrl+F` searches the transcript in fullscreen mode, and `Ctrl+Up`/`Ctrl+Down` jump between marked messages.
-- `Alt+P` cycles to the previous model.
-- `Ctrl+Z` undoes editing on native Windows; WSL uses `Alt+Z` so `Ctrl+Z` can suspend pi.
-- `Ctrl+Q` queues a follow-up message and `Alt+Q` restores queued messages.
+### Forward Shift+Enter
 
-Add to `settings.json` (Ctrl+Shift+, or Settings → Open JSON file) to forward `Shift+Enter` for inserting a new line:
+Open Windows Terminal's `settings.json` with `Ctrl+Shift+,` or **Settings > Open JSON file**. Add this object to its `actions` array:
 
 ```json
 {
-  "actions": [
-    {
-      "command": { "action": "sendInput", "input": "\u001b[13;2u" },
-      "keys": "shift+enter"
-    }
-  ]
+  "command": { "action": "sendInput", "input": "\u001b[13;2u" },
+  "keys": "shift+enter"
 }
 ```
 
-Windows Terminal binds `Alt+Enter` to fullscreen by default. To use it instead of pi's `Ctrl+Q` default for follow-up queueing, configure Windows Terminal to send the key and bind `app.message.followUp` to `alt+enter` in pi.
+Fully close and reopen Windows Terminal, then verify that `Shift+Enter` inserts a new line in Pi.
+
+### Use Alt+Enter for follow-ups
 
-If you already have an `actions` array, add the object to it. Fully close and reopen Windows Terminal after changing its settings.
+Windows Terminal binds `Alt+Enter` to fullscreen by default. Pi therefore uses `Ctrl+Q` for follow-ups on Windows and WSL.
 
-## xfce4-terminal, terminator
+To use `Alt+Enter` instead, configure Windows Terminal to forward the key and bind `app.message.followUp` to `alt+enter` in Pi's `keybindings.json`. See [Keybindings](keybindings.md#assign-keybindings).
 
-These terminals have limited escape sequence support. Modified Enter keys like `Ctrl+Enter` and `Shift+Enter` cannot be distinguished from plain `Enter`, preventing custom keybindings such as `submit: ["ctrl+enter"]` from working.
+## xfce4-terminal and Terminator
 
-For the best experience, use a terminal that supports the Kitty keyboard protocol:
-- [Kitty](https://sw.kovidgoyal.net/kitty/)
-- [Ghostty](https://ghostty.org/)
-- [WezTerm](https://wezfurlong.org/wezterm/)
-- [iTerm2](https://iterm2.com/)
-- [Alacritty](https://github.com/alacritty/alacritty) (requires compilation with Kitty protocol support)
+These terminals cannot reliably distinguish modified Enter keys from plain `Enter`. Custom bindings such as `Ctrl+Enter` or `Shift+Enter` therefore may not work.
 
-## IntelliJ IDEA (Integrated Terminal)
+Use a terminal with modern extended-key support when you need those shortcuts, such as Kitty, Ghostty, WezTerm, iTerm2, Windows Terminal, or a compatible Alacritty build.
 
-The built-in terminal has limited escape sequence support. Shift+Enter cannot be distinguished from Enter in IntelliJ's terminal.
+## IntelliJ IDEA integrated terminal
+
+IntelliJ IDEA's built-in terminal cannot reliably distinguish `Shift+Enter` from plain `Enter`. Use `Ctrl+J` for a newline or run Pi in a terminal with modern extended-key support.
+
+If an IME candidate window does not follow the text cursor, show the hardware cursor:
+
+```bash
+export PI_HARDWARE_CURSOR=1
+pi
+```
+
+## Override detected capabilities
+
+Pi automatically detects OSC 8 hyperlinks, inline image protocols, and truecolor support. A terminal proxy or multiplexer can make that detection inaccurate.
+
+| Capability | Environment variable | Setting |
+|---|---|---|
+| Hyperlinks | `PI_HYPERLINKS=1\|0\|auto` | `terminal.hyperlinks: true\|false\|"auto"` |
+| Inline images | `PI_IMAGE_PROTOCOL=kitty\|iterm2\|none\|auto` | `terminal.images: "kitty"\|"iterm2"\|false\|"auto"` |
+| Truecolor | `PI_TRUE_COLOR=1\|0\|auto` | `terminal.trueColor: true\|false\|"auto"` |
 
-If you want the hardware cursor visible, set `PI_HARDWARE_CURSOR=1` before running pi (disabled by default for compatibility).
+Settings take precedence over environment variables. An unset value or `auto` preserves automatic detection.
 
-Consider using a dedicated terminal emulator for the best experience.
+Only force a capability supported by the complete terminal path. Unsupported escape sequences can corrupt rendering. See [Environment Variables](environment-variables.md#pi-process-configuration) and [Settings](settings.md) for the canonical value definitions.

package/docs/termux.md

@@ -1,126 +1,117 @@
-# Termux (Android) Setup
+# Run Pi on Android with Termux
 
-Pi runs on Android via [Termux](https://termux.dev/), a terminal emulator and Linux environment for Android.
+Pi runs on Android through [Termux](https://termux.dev/), a terminal emulator and Linux environment. Text input, file tools, and shell commands are supported. Pi can copy and paste text through the Android clipboard with Termux:API. Clipboard image paste is not supported.
 
-## Prerequisites
+## Before you begin
 
-1. Install [Termux](https://github.com/termux/termux-app#installation) from GitHub or F-Droid (not Google Play, that version is deprecated)
-2. Install [Termux:API](https://github.com/termux/termux-api#installation) from GitHub or F-Droid for clipboard and other device integrations
+Install Termux from [GitHub or F-Droid](https://github.com/termux/termux-app#installation). Do not use the deprecated Google Play build.
 
-## Installation
+[Termux:API](https://github.com/termux/termux-api#installation) is optional. Install it only when you want Pi to copy or paste Android clipboard text, or when shell commands need Android device APIs.
 
-```bash
-# Update packages
-pkg update && pkg upgrade
+## Install Pi
 
-# Install dependencies
-pkg install nodejs termux-api git
+1. Update Termux packages:
 
-# Install pi
-npm install -g --ignore-scripts @earendil-works/pi-coding-agent
+   ```bash
+   pkg update && pkg upgrade
+   ```
 
-# Create config directory
-mkdir -p ~/.pi/agent
+2. Install Node.js and Git:
 
-# Run pi
-pi
-```
+   ```bash
+   pkg install nodejs git
+   ```
 
-## Clipboard Support
+3. Install Pi:
 
-Clipboard operations use `termux-clipboard-set` and `termux-clipboard-get` when running in Termux. The Termux:API app must be installed for these to work.
+   ```bash
+   npm install -g --ignore-scripts @earendil-works/pi-coding-agent
+   ```
 
-Image clipboard is not supported on Termux (the `ctrl+v` image paste feature will not work).
+4. Verify the installation:
 
-## Example AGENTS.md for Termux
+   ```bash
+   pi --version
+   ```
 
-Create `~/.pi/agent/AGENTS.md` to help the agent understand the Termux environment:
+5. Open the folder you want to work in and start Pi:
 
-````markdown
-# Agent Environment: Termux on Android
+   ```bash
+   cd /path/to/working-folder
+   pi
+   ```
 
-## Location
-- **OS**: Android (Termux terminal emulator)
-- **Home**: `/data/data/com.termux/files/home`
-- **Prefix**: `/data/data/com.termux/files/usr`
-- **Shared storage**: `/storage/emulated/0` (Downloads, Documents, etc.)
+Continue with the main [Quickstart](quickstart.md#3-choose-a-model) to connect a model and run your first task.
 
-## Opening URLs
-```bash
-termux-open-url "https://example.com"
-```
+## Access Android shared storage
 
-## Opening Files
-```bash
-termux-open file.pdf          # Opens with default app
-termux-open --chooser image.jpg      # Choose app
-```
+Termux cannot access shared Android storage until you grant permission. Run this once:
 
-## Clipboard
 ```bash
-termux-clipboard-set "text"   # Copy
-termux-clipboard-get          # Paste
+termux-setup-storage
 ```
 
-## Notifications
-```bash
-termux-notification -t "Title" -c "Content"
-```
+After approval, Android shared storage is available under `/storage/emulated/0` and through the links Termux creates under `~/storage/`.
 
-## Device Info
-```bash
-termux-battery-status         # Battery info
-termux-wifi-connectioninfo    # WiFi info
-termux-telephony-deviceinfo   # Device info
-```
+Only grant this permission when Pi should be able to access those files. Commands and tools running in Termux use the same storage permissions as the Termux process.
+
+## Use clipboard commands
+
+Pi uses `termux-clipboard-set` to copy text and `termux-clipboard-get` for its clipboard-paste shortcut. Shell commands can use both commands directly. Install the Termux:API app and its command-line package:
 
-## Sharing
 ```bash
-termux-share -a send file.txt # Share file
+pkg install termux-api
 ```
 
-## Other Useful Commands
+Verify the integration:
+
 ```bash
-termux-toast "message"        # Quick toast popup
-termux-vibrate                # Vibrate device
-termux-tts-speak "hello"      # Text to speech
-termux-camera-photo out.jpg   # Take photo
+printf 'Pi clipboard test' | termux-clipboard-set
+termux-clipboard-get
 ```
 
-## Notes
-- Termux:API app must be installed for `termux-*` commands
-- Use `pkg install termux-api` for the command-line tools
-- Storage permission needed for `/storage/emulated/0` access
-````
+The second command should print `Pi clipboard test`.
+
+The Termux clipboard API supports text only. Pi's clipboard-paste shortcut inserts that text into the editor but cannot attach clipboard images.
+
+## Add Termux-specific instructions
+
+Pi detects that it is running in Termux, but it cannot infer how you want it to interact with Android. Add only the environment details relevant to your work to `~/.pi/agent/AGENTS.md`:
 
-## Limitations
+````markdown
+# Termux environment
+
+- Pi runs in Termux on Android.
+- Shared Android storage is under `/storage/emulated/0`.
+- Open URLs with `termux-open-url "https://example.com"`.
+- Open files with `termux-open <path>`.
+- Do not access shared storage unless the task requires it.
+````
 
-- **No image clipboard**: Termux clipboard API only supports text
-- **Storage access**: To access files in `/storage/emulated/0` (Downloads, etc.), run `termux-setup-storage` once to grant permissions
+Run `/reload` after changing the file during an active session.
 
 ## Troubleshooting
 
-### Clipboard not working
+### Clipboard integration fails
 
-Ensure both apps are installed:
-1. Termux (from GitHub or F-Droid)
-2. Termux:API (from GitHub or F-Droid)
+Confirm that you installed both components:
 
-Then install the CLI tools:
-```bash
-pkg install termux-api
-```
+1. The Termux:API Android app from the same source as Termux
+2. The `termux-api` command-line package
 
-### Permission denied for shared storage
+Then run the clipboard verification commands above outside Pi. If they fail there, fix the Termux:API installation before retrying Pi's copy command.
 
-Run once to grant storage permissions:
-```bash
-termux-setup-storage
-```
+### Shared storage reports permission denied
+
+Run `termux-setup-storage`, approve the Android permission request, and retry the path under `~/storage/` or `/storage/emulated/0`.
 
-### Node.js installation issues
+### Pi is not found after installation
+
+Open a new Termux shell and run:
 
-If npm fails, try clearing the cache:
 ```bash
-npm cache clean --force
+npm prefix -g
+command -v pi
 ```
+
+Confirm that the global npm binary directory is on `PATH`, then reinstall Pi if the package is missing.