agent-shell-pet

agent-shell-pet adds Codex-compatible animated pets to Emacs agent-shell sessions. The Codex App isn’t required.

It listens to the public agent-shell event API, so it works with Codex, Claude, and other ACP-backed agents.

Features

• One global pet by default, notifying about all agent-shell buffers.
• Stacked activity cards for different agent-shell sessions.
• Click a native activity card to jump back to that session’s Emacs buffer.
• Hover a native activity card to reveal a dismiss button for that card.
• Visiting a session clears only that session’s current card.
• Optional one-pet-per-buffer mode.
• Portable Emacs child-frame renderer.
• macOS native renderer that floats above other app windows.
• Uses the same pet.json and spritesheet.webp format as Codex.app, so you can use any pet from codex-pets.net.
• Includes the /hatch-pet skill so you can create your custom pets easily.

Quick Start

(add-to-list 'load-path "/path/to/agent-shell-pet")
(require 'agent-shell-pet)

(global-agent-shell-pet-mode 1)

On macOS, build and use the native floating renderer:

make -C renderers/macos

(setq agent-shell-pet-renderer 'macos-native)

Doom Emacs

In $DOOMDIR/packages.el:

(package! agent-shell-pet
  :recipe (:host github :repo "lgmoneda/agent-shell-pet"
           :files ("*.el" "pets" "renderers")))

In $DOOMDIR/config.el:

(use-package! agent-shell-pet
  :after agent-shell
  :config
  (global-agent-shell-pet-mode 1))

Then run doom sync and restart Emacs.

Recommended Config

(add-to-list 'load-path "/path/to/agent-shell-pet")
(require 'agent-shell-pet)

(setq agent-shell-pet-renderer 'macos-native
      agent-shell-pet-speech-bubble-theme 'light
      agent-shell-pet-size 'medium)

(global-agent-shell-pet-mode 1)

Common Options

Choose a pet:

(setq agent-shell-pet-id "clawd")

Or choose interactively from every discovered avatar:

M-x agent-shell-pet-select-avatar

Use one pet per agent-shell buffer instead of one global pet:

(setq agent-shell-pet-scope 'buffer)

Adjust size:

(setq agent-shell-pet-size 'small)  ; 'large, 'medium, or 'small

Use the dark activity card:

(setq agent-shell-pet-speech-bubble-theme 'dark)

Completed turns stay visible for a short window, then collapse into a small badge that remains available as a jump target until you visit the related agent-shell buffer:

(setq agent-shell-pet-completion-display-seconds 20.0)

Optionally play a sound when a turn completes successfully:

(setq agent-shell-pet-completion-sound-enabled t)

Customize the sound behavior with agent-shell-pet-completion-sound-function. On macOS, the default function first plays the standard Glass.aiff system sound with afplay before falling back to Emacs’ built-in ding.

When global-agent-shell-pet-mode is enabled, the package runs agent-shell-pet-global-mode-enable-hook. Use it for personal integrations that should run when the global pet takes over agent-shell notifications.

Installing More Pets

agent-shell-pet discovers pets from:

• agent-shell-pet-user-pets-directory
• ${CODEX_HOME:-$HOME/.codex}/pets/
• the package’s bundled pets/ directory

Install from codex-pets.net into the Emacs pet directory:

(agent-shell-pet-install-from-codex-pets "https://codex-pets.net/#/pets/canarinho")

Install into the Codex pet directory instead:

(agent-shell-pet-install-from-codex-pets "canarinho" 'codex)

Pets installed with the Codex CLI are picked up too:

npx codex-pets add canarinho

Pet Format

<pet-id>/
├── pet.json
└── spritesheet.webp

Atlas requirements:

• 1536x1872
• 8 columns by 9 rows
• 192x208 cells
• transparent PNG or WebP source, packaged as spritesheet.webp

For creating new pets, see docs/hatch-pet.org.

Commands

• M-x global-agent-shell-pet-mode
• M-x agent-shell-pet-show
• M-x agent-shell-pet-hide
• M-x agent-shell-pet-select-avatar
• M-x agent-shell-pet-wave
• M-x agent-shell-pet-macos-build-helper

Development

Run tests:

emacs --batch -L . -l tests/agent-shell-pet-tests.el -f ert-run-tests-batch-and-exit

Byte-compile:

emacs --batch -L . -f batch-byte-compile agent-shell-pet.el