Agent Peeps docs

Everything agentpeeps can do.

Commands, sticker rules, the config file, the event log and the APIs. One page, local only, no account.

Quick start

One command adds hooks to every supported agent it finds. Your existing settings are backed up first.

$ npx agentpeeps init

Prefer a global install? Same thing, and the command stays on your PATH:

$ npm i -g agentpeeps
$ agentpeeps init
  1. Start a new agent session. Hooks load when a session starts, so the stickers appear from the next one. To start them now: agentpeeps overlay.
  2. Codex: open /hooks once and trust the Agent Peeps hooks. Codex never runs new hooks without asking.
  3. Copilot and Antigravity: restart them so they read the new hook files.

The old command name agent-presence still works. Settings live in ~/.agent-presence/ either way.

Supported agents

init with no arguments sets up every agent whose folder it finds. Name agents to pick: agentpeeps init claude codex.

AgentHooks written toEvents
Claude CodeCLI, desktop app, IDE~/.claude/settings.jsonSessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Notification, SubagentStart, SubagentStop, Stop, SessionEnd. Async, never blocks.
Codex~/.codex/hooks.jsonSame as Claude, plus PermissionRequest. Trust them once in /hooks.
CopilotVS Code agent mode, Copilot CLI~/.copilot/hooks/agent-presence.jsonsessionStart, userPromptSubmitted, postToolUse, notification, subagentStart, subagentStop, agentStop, sessionEnd. 5 s timeout.
Antigravity~/.gemini/config/hooks.json, key "agent-presence"SessionStart, PostToolUse, Stop.

Copilot and Antigravity run hooks synchronously and treat a failing pre-tool hook as “deny”, so Agent Peeps only listens to events that can't block them. A tool call shows up when it finishes, not when it starts.

CLI reference

Run agentpeeps with no arguments for this list in your terminal.

agentpeeps init [agent...]

Installs hooks for claude, codex, copilot, antigravity (default: every one found), backs up each file it touches (.bak-agent-presence), and starts the overlay. Run it again any time to update.

$ agentpeeps init
Installed hooks for: Claude Code (~/.claude/settings.json), Codex (~/.codex/hooks.json)
Codex: open /hooks in Codex once and trust the Agent Peeps hooks.
The stickers appear on your next agent session. To start them now: agentpeeps overlay

Run through npx, it first installs a permanent copy into ~/.agent-presence/app and points the hooks there, because npx may clear its cache.

agentpeeps uninstall [agent...]

Removes only the Agent Peeps hooks. Your own hooks and settings stay.

agentpeeps overlay [--quit]

Starts the floating stickers, or stops them with --quit. It also starts on its own at the next session start unless autostart is off.

agentpeeps control [target]

Opens the control room. Pass a target to open straight on its stickers: agentpeeps control codex, agentpeeps control helpers. Aliases: stickers, settings.

agentpeeps packs

Lists every sticker pack: your folders first, then the bundled ones.

$ agentpeeps packs
Sticker packs (use one with: agentpeeps set <target> <pack>)

  capybaras                   16 stickers  (bundled)
  cats                        54 stickers  (bundled)
  fruit-cats                   6 stickers  (bundled)

agentpeeps set <target> <pack|image|default> [more...]

Points a target at a pack, an image, or several of both. default (or none, reset) goes back to the colored disc. Singular and plural pack names both work. Targets are listed under Stickers.

$ agentpeeps set claude capybaras
claude -> capybaras pack (16 stickers)
Each session gets its own sticker from the set. The overlay updates live.
$ agentpeeps set codex cats
$ agentpeeps set helpers fruit-cats
$ agentpeeps set model:opus capybaras
$ agentpeeps set Explore ~/stickers/detective.png
$ agentpeeps set claude default

agentpeeps watch

The same live view in your terminal: every agent, its helpers, and the last four files each one touched, relative to its project.

Agent Peeps  (Ctrl+C to exit)

  ✏️  claude 3f9a1c              writing    src/login.ts  (2s)
          ✏️ src/login.ts  2s
          🔍 src/auth.ts  9s
      🔍  └ Explore              reading    tests  (4s)

agentpeeps emit <agent> [event]

Used by the hooks: reads the hook's JSON on stdin and appends one line to the event log. It always exits 0, so it can never break or slow your agent. Copilot and Antigravity pass the event name as the second argument and get {} back on stdout.

Stickers

Every session shows the colored disc for its agent until you pick stickers: C Claude, X Codex, P Copilot, A Antigravity. Helpers get a white disc ringed in their parent's color.

Packs

A pack is any folder of images. Yours live in ~/.agent-presence/stickers/<pack>/, and a folder of yours wins over a bundled pack with the same name. PNG, GIF (animation plays), SVG, WebP or JPEG; square, about 256 px.

Targets

TargetWho it applies to
claude codex copilot antigravityEvery session of that agent.
model:<text>Sessions whose model contains the text, e.g. model:opus, model:fable.
helpersEvery subagent. Saved as subagent.
claude-helpers, codex-helpers, …One agent's subagents. Saved as claude-subagent.
Explore, any type nameOne subagent type.

Which sticker wins

  • Sessions: the longest matching model: rule, then the agent, then the default disc.
  • Helpers: their type, then <agent>-subagent, then subagent, then the default disc.
  • A pack or a list gives each session (or helper) one sticker of its own, picked by its id, so it keeps the same face all session.

Sponsoring

Agent Peeps is free and open source, and so is every sticker on the site: the packs, the animated ones and the sticker maker.

If your team uses it, you can sponsor the project to keep it free and local-first for everyone. Or just buy me a coffee from the same page.

Control room

One window for every setting, so you never edit a file or spend tokens asking an agent. Changes apply the moment you click. Open it with Ctrl Alt Shift C, the tray icon, agentpeeps control, or right-click a sticker → Change sticker…. It loads in the background when the overlay starts, so it opens instantly, and closing it only hides it.

Overview: what every agent is doing

A live board of every agent session on this machine, fed by the same hooks as the stickers.

Display: how the stickers sit on screen

Only over my apps hides the stickers whenever another app is in front, and brings them back when you switch to your editor or terminal. Highlighted chips count as yours; dashed ones were in front recently and are one click away. Switching to the control room never hides them. It works on Windows and macOS, and on Linux under X11 with xdotool; where the app in front can't be detected, the stickers simply show everywhere.

Helpers (subagents) can show which agent they belong to in three ways:

A Claude sticker with two smaller helper stickers joined to it by a thin orange line
Joining line The default. A thin line in the agent's color.
Helper stickers inside a dashed pill in Claude's color
Dashed pod Helpers sit in a tinted pill with the agent's letter.
Helper stickers next to the Claude sticker with nothing joining them
Side by side No decoration at all.

Speech bubbles: the card on each sticker

Hover a sticker to see what it's doing. Click it to pin the bubble open (it gets an outline in the agent's color); click again to unpin. A bubble opens by itself when an agent needs you.

Dark bubble card with white text
Card, dark White text. Auto picks this in dark mode.
Light bubble card with black text
Card, light Black text. Auto picks this in light mode.
Bubble text with no card behind it, just a soft shadow
Text only No card, just a soft shadow behind the letters.
Light bubble with no border and blue text
No border, custom color Any text color from the picker.

Keyboard shortcuts

Everything you change often has a global shortcut, so you never need to open the window. A small toast at the bottom of the screen confirms each one. On macOS use ⌘ ⌥ ⇧ instead of Ctrl Alt Shift.

ShortcutWhat it does
CtrlAltShiftAShow or hide the stickers (always on)
CtrlAltShiftCOpen the control room
CtrlAltShiftFEverywhere, or only over my apps
CtrlAltShiftBSpeech bubbles on or off
CtrlAltShiftPPeek: open every bubble at once
CtrlAltShiftTBubble theme: auto, dark, light
CtrlAltShiftDDetails in the bubble, or always under each sticker
CtrlAltShiftSNext size: small, medium, large
CtrlAltShiftWWhen to show: while working, only when it needs you, always
CtrlAltShiftLHelper layout: line, pod, side by side
CtrlAltShiftMMotion: lively, calm, off
CtrlAltShiftHHide for 30 minutes
CtrlAltShiftRReset sticker positions

Stickers: one set per agent, helper or model

The left column lists every target: each agent, each agent's helpers, every helper, helper types that have shown up (Explore, test-writer…) and model rules (type opus and press Add). Pick one image, several (each session or helper gets its own), or a whole pack. Add from my computer… copies nothing; it points at your files.

On the stickers

A Claude sticker with a red pulse ring and an open bubble saying it needs permission to use Bash
Needs you A pulse ring, a red badge, and the bubble opens by itself.
Stickers with a short status line under each one
Details: always One short line under each sticker.
  • Drag an agent's sticker anywhere; it remembers the spot. Reset positions (or CtrlAltShiftR) puts them back in the corner.
  • Hover for who, what, its recent files and its stats; click a file to show it in your file manager.
  • Click a sticker to pin its bubble open. Peek (CtrlAltShiftP) opens them all.
  • Right-click for Change sticker…, Hide this agent, Peek, Hide for 30 minutes, Size and Quit.
  • Motion: Lively adds a pulse ring when an agent needs you, a small hop on each step and a bounce when it finishes. Calm keeps only slow loops; Off stops everything.
  • With no sticker chosen, each agent shows its own logo. Clicks pass straight through everywhere except on the stickers, and a session that goes quiet for 15 minutes disappears.

Updated Agent Peeps while it was running? The control room says Restart Agent Peeps to finish updating. Run agentpeeps overlay --quit, then agentpeeps overlay.

Config file

~/.agent-presence/config.json (Windows: %USERPROFILE%\.agent-presence\config.json). The control room and set write it; you can edit it by hand and the overlay applies changes live. The VS Code extension reads it too.

{
  "avatars": {
    "claude": "pack:capybaras",
    "model:opus": ["pack:capybaras", "~/stickers/fox.png"],
    "codex": "pack:cats",
    "claude-subagent": "pack:fruit-cats",
    "subagent": "pack:pixel-food",
    "Explore": "~/stickers/detective.png"
  },
  "names": { "claude": "Foxy" },
  "size": "small",
  "show": "working",
  "details": "hover",
  "agents": { "copilot": false, "subagent": true },
  "autostart": true,
  "scope": "apps",
  "apps": ["Code", "Cursor", "WindowsTerminal"],
  "helpers": "line",
  "motion": "lively",
  "icon": true,
  "opacity": 80,
  "shortcuts": true,
  "bubble": { "on": true, "style": "card", "border": true, "theme": "auto", "text": "auto", "size": "medium", "auto": true, "stats": true }
}
KeyTypeMeaning
avatarsobjectTarget → image path, "pack:<name>", or a list of both. ~ is allowed.
namesobjectDisplay name per agent, e.g. {"claude": "Foxy"}.
sizestringsmall (default) · medium · large
showstringworking (default) · alerts · always
detailsstringhover (default) · always
agentsobjectfalse hides an agent; "subagent": false hides all helpers.
autostartbooleanfalse stops the overlay opening on new sessions. Default true.
scopestringeverywhere (default) · apps: only while an app in apps is in front
appsarrayProcess names (Windows), app names (macOS) or commands (Linux) that count as yours. Defaults to common editors and terminals.
helpersstringline (default) · pod · none
motionstringlively (default) · calm · off
iconbooleanfalse hides the small status badge. Default true.
opacitynumber30 to 100. Stickers rest at this opacity until you hover them. Default 100.
shortcutsbooleanfalse turns off every global shortcut except show / hide. Default true.
bubbleobjecton, border, auto (open when it needs you), stats: booleans, all true by default · style: card or text · theme: auto, dark or light · text: auto or a color like #ffd166 · size: small, medium or large

Event log

Every hook call becomes one JSON line in ~/.agent-presence/events.jsonl. The overlay, watch and VS Code all tail this file, so anything you build can too. It rolls over to events.jsonl.old at 5 MB.

{"t":1794788741918,"agent":"claude","session":"3f9a1c…","sub":null,"subType":null,"event":"PreToolUse","state":"writing","tool":"Edit","file":"/repo/src/login.ts","detail":null,"cwd":"/repo","model":"claude-opus-5-5"}
FieldMeaning
tTime in ms.
agentclaude · codex · copilot · antigravity
sessionSession or conversation id.
sub, subTypeHelper id and type (e.g. Explore); null for the main session.
event, toolThe hook event and the tool name, as the agent sent them.
stateWhat the sticker shows (below).
fileFile being read or written, when there is one (also parsed out of Codex patches).
detailCommand, search, URL, helper task or the reason it needs you.
cwd, modelProject folder and model, when the agent sends them.

States

    VS Code extension

    Shows the same activity inside VS Code, Cursor and Windsurf: a badge on every file an agent is touching, colored by agent, and an Agents view in the Explorer listing sessions and helpers. It reads the same event log, so it needs the hooks from agentpeeps init.

    🅒 Claude🅧 Codex🅟 Copilot🅐 Antigravity🅔 an Explore helper

    SettingDefaultMeaning
    agentPresence.badges{"claude":"🅒", …}Badge per agent, subagent or helper type; 1–2 characters or one emoji.
    agentPresence.recentSeconds90How long a file keeps its badge after an agent stops touching it.

    Colors are themeable as agentPresence.claude, .codex, .copilot, .antigravity, .subagent, .other. Custom stickers from config.json show up in the Agents view.

    Node API

    For tools and contributors. require('agentpeeps/cli.js') exports:

    normalize(agent, hookJson, event?)
    Turns any agent's hook payload into one event line (or null for events it ignores).
    patchFiles(patchText)
    File paths named in a Codex apply_patch body.
    editHooksFile(file, events, makeHook, remove)
    Adds or removes our hook in a Claude/Codex style hooks file, keeping everything else and writing a backup.
    copilotHooks(file, cli, remove)
    Writes or deletes ~/.copilot/hooks/agent-presence.json.
    antigravityHooks(file, cli, remove)
    Adds or removes the "agent-presence" group in Antigravity's hooks file.
    isEphemeral(dir)
    true when running from an npx / dlx / bunx cache.
    packs()
    Map of pack slug → { name, dir, files, mine }.
    stickerFiles(value, packs?)
    Resolves a config value (path, "pack:x" or a list) to existing image files.
    targetKey(target)
    What people type → config key: helpers → subagent, claude-helpers → claude-subagent.
    slug(text)
    Pack-name slug: lowercase, dashes.
    HOME, EVENTS, CONFIG
    Paths of ~/.agent-presence, the event log and the config file. AGENT_PRESENCE_HOME overrides HOME.

    Overlay bridge

    The overlay pages talk to Electron through window.ap (overlay/preload.js). Every message is validated in the main process.

    CallDoes
    onConfig(cb) · onEvent(cb) · onResetPositions(cb)Config changes, new events, position reset.
    mouse(over)Lets clicks through unless the pointer is over a sticker.
    reveal(file, cwd) · menu(target)Show a file in the file manager · open the right-click menu.
    onRoom(cb) · setAvatars(key, files) · browse(key)Control room data · choose stickers · pick files from disk.
    setConfig(patch) · setVisible(on) · resetPositions() · openFolder()Save settings · show/hide · reset drag positions · open the sticker folder.

    Agent skill

    The package ships a skill for Claude Code and Codex, so you can just ask: “give Codex the cat stickers”, “make the stickers smaller”, “only show them when an agent needs me”. The agent runs agentpeeps set or edits config.json. It never touches your hook settings. For one-off changes the control room is faster and costs no tokens.

    Privacy

    Local only: no server, no account, no network calls, no telemetry. Hooks write to a file in your home folder and the overlay reads it. Nothing leaves your machine.

    Uninstall

    $ agentpeeps uninstall
    $ agentpeeps overlay --quit
    $ npm rm -g agentpeeps

    Then delete ~/.agent-presence/ if you want your stickers and settings gone too.

    Troubleshooting

    No stickers appear
    Start a new session; hooks load at session start. Then check that ~/.agent-presence/events.jsonl grows while the agent works, and run agentpeeps overlay.
    Codex shows nothing
    Open /hooks in Codex and trust the Agent Peeps entries.
    Stickers stopped after an update or a cache clean
    Run agentpeeps init again. With npx it reinstalls the permanent copy in ~/.agent-presence/app.
    The control room says "Restart Agent Peeps to finish updating"
    The copy that is running is older than the one installed. Run agentpeeps overlay --quit, then agentpeeps overlay.
    A shortcut says "used by another app"
    Another program registered the same keys first. Close it, or turn global shortcuts off in the control room; CtrlAltShiftA keeps working either way.
    "Only over my apps" hides the stickers in my editor
    Open Display in the control room, switch to your editor and back: its name shows up as a dashed chip. Click it to add it.
    Copilot or Antigravity show only finished steps
    Expected: their hooks can't run in the background, so tool calls show when they finish.
    Testing by hand on Windows
    PowerShell pipes a byte-order mark; emit strips it. Set AGENT_PRESENCE_DEBUG=1 to print hook errors.