feat(tui): add ambient terminal pets

[fcoury-oai]

Why

The Codex App has animated pets, but the TUI had no equivalent ambient companion surface. This brings that experience into terminal Codex while keeping the main chat flow usable: the pet should feel present, but it cannot cover transcript text, composer input, approvals, or picker content.

The feature also needs to be terminal-aware. Different terminals support different image protocols, tmux can interfere with image rendering, and some users will want pets disabled entirely or anchored differently depending on their layout.

macOS - Ghostty, iTerm2 and WezTerm with Custom Pet

![Uploading CleanShot 2026-05-10 at 20.28.30.png…]() Windows Terminal

Linux - WezTerm and Ghostty

What Changed

• Add a TUI ambient pet renderer in codex-rs/tui/src/pets/.
• Port the app-style pet animation states so the sprite changes with task status, waiting-for-input states, review/ready states, and failures.
• Add /pets selection UI with a preview pane, loading state, built-in pet choices, and a first-row Disable terminal pets option.
• Download built-in pet spritesheets on demand from the same public CDN path already used by Android, under https://persistent.oaistatic.com/codex/pets/v1/..., and cache them locally under ~/.codex/cache/tui-pets/.
• Keep custom pets local.
• Add config support for pet selection, disabling pets, and choosing whether the pet follows the composer bottom or anchors to the terminal bottom.
• Reserve layout space around the pet so transcript wrapping, live responses, and composer input do not render underneath the sprite.
• Gate image rendering by terminal capability, disable image pets under tmux, and support both Kitty Graphics and SIXEL terminals.
• Add redraw cleanup for terminal image artifacts, including sixel cell clearing.

Current Scope

• This is an initial TUI version of ambient pets, not full App parity.
• It focuses on ambient sprite rendering, /pets selection, custom pets, terminal capability gating, and on-demand CDN-backed built-in assets.
• The ambient text overlay is currently disabled, so the TUI renders the pet sprite without extra status text beside it.

How to Test

1. Start Codex TUI in a terminal with image support.
2. Run /pets.
3. Confirm the picker shows built-in pets plus custom pets, and the first item is Disable terminal pets.
4. On a fresh ~/.codex/cache/tui-pets/, move onto a built-in pet and confirm the first preview downloads the spritesheet from the shared Codex pets CDN and renders successfully.
5. Move through the pet list and confirm subsequent built-in previews use the local cache.
6. Select a pet, then send and receive messages. Confirm transcript and composer text wrap before the pet instead of rendering underneath the sprite.
7. Change the pet anchor setting and confirm the pet can either follow the composer bottom or sit at the terminal bottom.
8. Return to /pets, choose Disable terminal pets, and confirm the sprite disappears cleanly.

Targeted tests:

• cargo test -p codex-tui ambient_pet_
• cargo test -p codex-tui resize_reflow_wraps_transcript_early_when_pet_is_enabled
• cargo insta pending-snapshots

[fcoury-oai]

@etraut-openai I have internalized the Sixel processing along with the rest of your feedback. Ready for another pass.

[etraut-openai]

This is a really large PR, which makes it difficult to review in its entirety.

I did skim through the code, and I found a few issues (some with the help of codex).

I did a bunch of manual testing in various terminals — both those that support the graphics escapes and those that don't (all on macOS). It seems to work well.

I also verified that the total binary size increase. It's about 0.92MiB or a 0.5% increase, which is somewhat high for a single TUI feature, but I think it's within reason.

[fcoury-oai]

@etraut-openai thanks a lot for the review. I addressed them all, please do another pass when you can.

[etraut-openai]

PR looks good.

I built the latest and did a quick smoke test.

I think there's room for some additional simplification, so consider running "simplify" pass on it before merging. See slack DM for details.