Guide

Claude Code, Codex, Copilot and Antigravity hooks, compared.

All four major coding agents now have hooks, but they differ in where the config lives, which events fire, and whether a slow hook holds the agent up. Notes from building one tool on all four.

At a glance

Config fileRuns in backgroundAsks before trusting
Claude Code~/.claude/settings.jsonyes, with "async": trueno
Codex~/.codex/hooks.jsonyes, with "async": trueyes, approve in /hooks
GitHub Copilot~/.copilot/hooks/*.jsonno, runs in lineno
Antigravity~/.gemini/config/hooks.jsonno, runs in lineno

These are the files and behaviours Agent Peeps relies on today. Agents change quickly, so check each one's docs before building on a detail.

Claude Code

The richest set of events: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Notification, SubagentStart, SubagentStop, Stop and SessionEnd. Payloads are snake_case (session_id, tool_name, tool_input) and SessionStart includes the model. Hooks can be async, so an observer never slows a session. Details in Claude Code hooks explained.

Codex

Close to Claude Code in shape: the same snake_case fields and most of the same events, plus PermissionRequest for the moment it needs approval. Two differences: file edits go through apply_patch, so the file names are inside the patch text (*** Update File: src/a.ts), and Codex won't run a new hook until you approve it in /hooks.

GitHub Copilot (VS Code agent mode and Copilot CLI)

Both read hook files from ~/.copilot/hooks/ (or $COPILOT_HOME). Events are camelCase (sessionStart, userPromptSubmitted, postToolUse, notification, agentStop...) and tool arguments arrive as a JSON string in toolArgs. Hooks run synchronously and stdout is read as a decision, so a hook should print {} ("no opinion") and exit quickly. A failing pre-tool hook can deny the call, which is why Agent Peeps listens only after tools finish.

Antigravity

Hooks live in ~/.gemini/config/hooks.json as named groups, so several tools can share the file without stepping on each other. Payloads carry conversationId, a toolCall with name and args, and modelName. Like Copilot, hooks run in line and stdout is a decision.

What this means if you build on hooks

  • Normalize early. Map every agent's payload to one shape (agent, session, event, tool, file) at the edge.
  • Never block. Where hooks are synchronous, only listen to events that can't hold the agent up, and keep the hook to a file append.
  • Guess tool states from names. Tool names differ per agent (Edit, apply_patch, str_replace_editor, run_command); a keyword match covers new ones.
  • Back up before you edit someone's settings file, and remove only your own entries on uninstall.

All of this is in Agent Peeps' cli.js, MIT licensed.

Try it in one command

Agent Peeps is free and open source (MIT). It only reads hook events on your machine: no account, no server, no network.

$ npx agentpeeps init
$ npx agentpeeps overlay

See the stickers in your browser · Read the docs · Star it on GitHub