CGx's pi-emote

Currently looking to expand the emotes gallery! If you have an emote set you'd like to submit, please make a PR!

Animated pixel-art emote that lives in the top-right corner of your pi TUI session. Reacts to what the agent is doing — thinking, talking, reading, writing, using tools, etc.

Supports Kitty, iTerm2, and ASCII rendering.

Gallery

Community-contributed emote sets. Submit yours via PR!

Image Sets

Avatar	Name	Contributor
	default	@cgxeiji
	aza_choi	@shennguyenrs
	aza_choi_nobg	@shennguyenrs
	red	@cgxeiji

ASCII Sets

Avatar	Name	Contributor
(^ ◡ ^)/	ascii	@cgxeiji
ʕ•̫͡•ʔ	ascii-bear	@LCorleone

Install

pi install git:github.com/cgxeiji/pi-emote

States

State	Trigger
hi	Session start
idle	Nothing happening (blinks occasionally)
think	Reasoning tokens streaming
talk	Text response streaming
read	read tool / reading tool output
write	write or edit tool
tool	Any other tool
success	Successful tool execution
failure	Failed tool execution
compact	Context compaction

Config

Drop a config.json in one of these paths (highest priority wins):

• ~/.pi/agent/extensions/pi-emote/config.json — your global prefs
• .pi/extensions/pi-emote/config.json — project override

Only include what you want to change:

{
  "size": 12,
  "emotes": [
    { "model": "*claude*", "emote-set": "my-avatar" }
  ]
}

See config.json in the extension root for all defaults.

Multiplexers

pi-emote can render image avatars through tmux using DCS passthrough. When tmux is detected, pi-emote auto-detects the outer terminal and picks the right image protocol.

tmux Setup

Add these to your tmux.conf:

# Required — allow image sequences to pass through to the outer terminal
set -g allow-passthrough on

# Required — detect outer terminal when attaching from a different terminal
set -ga update-environment TERM
set -ga update-environment TERM_PROGRAM

# Recommended — reduces flicker during animation
set -sg escape-time 0

Then restart tmux completely:

tmux kill-server && tmux

Without allow-passthrough, pi-emote defaults to ASCII and shows a one-time warning with setup instructions.

Experimental Multiplexer Support

Outer Terminal	Protocol	Status
Ghostty	kitty-unicode	✅ Stable, pane-safe, auto-detected
kitty	kitty-unicode	⚠️ Untested, pane-safe, auto-detected
iTerm2	iterm2	⚠️ Experimental, opt-in only (pane bleed in multi-pane layouts)
WezTerm	iterm2	⚠️ Experimental, opt-in only (not verified)

The outer terminal is detected via tmux show-environment TERM_PROGRAM, which reflects the currently attached terminal.

Ghostty and kitty use the kitty-unicode renderer (Unicode placeholders) which is pane-safe — images stay within their pane and clean up on session switch. This is the default when auto-detected.

iTerm2 and WezTerm use DCS passthrough for the iTerm2 image protocol. This works but has known limitations: images can bleed into adjacent panes and persist when switching sessions. Not enabled by default — opt in explicitly:

{
  "terminals": [
    { "match": "tmux", "render": "iterm2" }
  ]
}

Other Multiplexers

zellij and screen are not yet supported and default to ASCII.

Manual Override

Force a specific renderer:

{
  "terminals": [
    { "match": "tmux", "render": "kitty-unicode" }
  ]
}

Available render values for tmux: "auto", "kitty-unicode", "kitty", "iterm2", "ascii".

• "auto" — detect outer terminal; uses kitty-unicode for Ghostty/kitty, ASCII for others
• "kitty-unicode" — pane-safe Unicode placeholders (Ghostty, kitty)
• "kitty" — classic DCS passthrough (single-pane only, experimental)
• "iterm2" — iTerm2 DCS passthrough (single-pane only, experimental)
• "ascii" — text fallback

Custom Emotes

Emote sets live in emotes/<set-name>/ with PNG frames per state:

emotes/my-avatar/
├── idle/*.png
├── think/*.png
├── talk/*.png
├── read/*.png
├── write/*.png
├── tool/*.png
└── ...          # hi, success, failure, compact

Not all states are required. Missing ones just won't animate.

Where to put them

pi-emote searches in order:

1. .pi/extensions/pi-emote/emotes/<name>/ (project)
2. ~/.pi/agent/extensions/pi-emote/emotes/<name>/ (user)
3. Extension built-in → falls back to default

Map models to sets

Glob patterns against model ID, last match wins:

{
  "emotes": [
    { "model": "*", "emote-set": "default" },
    { "model": "*claude*", "emote-set": "my-avatar" },
    { "model": "*haiku*", "emote-set": "haiku-avatar" }
  ]
}

In this example, claude models use my-avatar, but haiku ones use haiku-avatar. See emotes/default/emotes.json for per-set frame config (blink frames, talk weights).

License

MIT