Terminal setup
PiG runs in any terminal. Some features need terminal support, and PiG turns each one on only when it detects that support. This page lists what PiG detects, and what to change when a key or an image does not work.
What PiG detects
PiG reads environment variables to decide what your terminal accepts. It does not ask the terminal, because a terminal that does not answer would delay startup.
Terminal | Images | True color | Hyperlinks |
| Kitty | yes | yes | yes |
| Ghostty | yes | yes | yes |
| WezTerm | yes | yes | yes |
| iTerm2 | yes | yes | yes |
| VS Code | no | yes | yes |
| Alacritty | no | yes | yes |
| Apple Terminal | no | yes | no |
| Warp | no | yes | yes |
| Windows Terminal | no | yes | no |
Inside tmux or screen, PiG turns images and hyperlinks off. The multiplexer
sits between PiG and the terminal, so what the outer terminal accepts is not
evidence that the pane accepts it.
PiG reads TERM_PROGRAM, TERM and COLORTERM first. It also accepts
KITTY_WINDOW_ID, GHOSTTY_RESOURCES_DIR, WEZTERM_PANE, ITERM_SESSION_ID
and WT_SESSION as evidence, because some terminals set only these.
Keys that do not respond
A terminal sends a key to PiG only if it does not use the key itself. When a binding does nothing, the terminal usually consumed the key.
Check first whether the key works outside PiG. If the terminal has a command bound to it, unbind the command or bind the PiG action to a different key. See keybindings.
tmux
tmux must send extended keys, or modified keys such as shift+enter and
ctrl+enter arrive as their unmodified form. PiG warns at startup when it finds
the wrong setting.
Add both lines to ~/.tmux.conf and restart tmux:
set -g extended-keys on
set -g extended-keys-format csi-uextended-keys-format xterm also sends modified keys, but in a format that
carries less information. PiG warns about it and works better with csi-u.
PiG does not warn when it cannot query tmux, because a sandbox that blocks the query is not evidence of a wrong setting.
Termux
Termux reports its window size differently from a desktop terminal. PiG detects
Termux with TERMUX_VERSION and does not repaint the whole buffer when the
window changes, because the repaint costs more than it corrects there.
Images
PiG shows images when the terminal accepts the Kitty graphics protocol or the iTerm2 protocol. In every other terminal PiG writes the file path instead, so no information is lost.
Images are off inside tmux and screen. To see images, run PiG outside the
multiplexer.
Display problems
Symptom | Cause | What to do |
| scrolling up jumps to the top | a component wrote a row wider than the terminal | PiG wraps such a row and records it in ~/.pig/agent/pig-overflow.log; send that file |
| colors look wrong | the terminal reports no true color | set COLORTERM=truecolor if the terminal supports it |
a stray [?62;22c appears | the terminal answered a capability query late | PiG consumes this answer; report it with the terminal name |
Set PIG_RENDER_DEBUG to any value to write render diagnostics. Use it when you
report a display problem.
PiG also writes ~/.pig/agent/pig-overflow.log on its own when a component
writes a row wider than the terminal. That file names the component, so send it
with the report.
Related
- Keybindings lists the actions and their default keys.
- Settings lists the files and settings PiG reads.