Skip to content

terminal-setup.md

Latest commit

 

History

History
110 lines (79 loc) · 2.65 KB

terminal-setup.md

File metadata and controls

110 lines (79 loc) · 2.65 KB

Terminal Setup

Pi works in any modern terminal, but some features (like image display) and key combos require terminal-specific support or configuration.

Recommended Terminals

  • Ghostty: Excellent performance and Kitty graphics support.
  • WezTerm: Great cross-platform support and iTerm graphics protocol.
  • iTerm2: Solid iTerm graphics protocol support (macOS).
  • Kitty: Best-in-class Kitty graphics support.
  • Windows Terminal: Good Unicode support, limited inline image support.

Keyboard Protocol Notes

Some terminals need Kitty keyboard protocol enabled for reliable modifier combos (e.g., Shift+Enter, Alt+Backspace).

Ghostty

Add to ~/.config/ghostty/config:

keybind = alt+backspace=text:\x1b\x7f
keybind = shift+enter=text:\n

WezTerm

Create ~/.wezterm.lua:

local wezterm = require 'wezterm'
local config = wezterm.config_builder()
config.enable_kitty_keyboard = true
return config

VS Code (Integrated Terminal)

Add to keybindings.json:

{
  "key": "shift+enter",
  "command": "workbench.action.terminal.sendSequence",
  "args": { "text": "\u001b[13;2u" },
  "when": "terminalFocus"
}

Windows Terminal

Add to settings.json:

{
  "actions": [
    {
      "command": { "action": "sendInput", "input": "\u001b[13;2u" },
      "keys": "shift+enter"
    }
  ]
}

IntelliJ IDEA (Integrated Terminal)

IntelliJ’s terminal can’t distinguish Shift+Enter from Enter. For the best experience, use an external terminal.

If you want the hardware cursor visible, set PI_HARDWARE_CURSOR=1 before running pi.

Image Support

Pi detects terminal capabilities to display images inline (currently Kitty-compatible terminals such as Kitty, WezTerm, and Ghostty, plus iTerm2). For unsupported terminals, Pi falls back to a stable placeholder such as [image: image/png, 1024x768].

To block images entirely, set:

{
  "images": {
    "block_images": true
  }
}

You can also hide image blocks in terminal output:

{
  "terminal": {
    "show_images": false
  }
}

terminal.show_images controls whether Pi includes image blocks in terminal tool output (defaults to true).

terminal.clear_on_shrink (defaults to false) purges scrollback when the terminal height shrinks, which helps avoid stale rows reappearing after a resize.

Keybindings

Some terminals intercept key combinations needed by Pi (e.g., Ctrl+Arrow, Shift+Enter).

  • Windows Terminal: Use Ctrl+Enter for newlines if Shift+Enter isn’t available.
  • VS Code Terminal: Some shortcuts may be captured by VS Code. Check your terminal.integrated.commandsToSkipShell setting.