Skip to content

Glossary

Agent hooks

Last updated

Definition

Agent hooks are commands that an AI coding agent such as Claude Code or Codex runs automatically at set points in its lifecycle, for example when a session starts, before or after a tool call, on a permission request, or when a turn stops.

Also called: hooks, Claude Code hooks, Codex hooks, lifecycle hooks.

Each hook is tied to an event, can be limited to certain tools with a matcher, and receives the event's details as JSON. Most hooks are shell commands, though Claude Code also supports HTTP, prompt and MCP tool hooks. Hooks are used to log activity, block risky commands, run checks when a turn ends, or tell another app what the agent is doing. Because a hook runs with your account's access, only add hooks you trust.

Claude CodeCodex
Where they're set"hooks" in ~/.claude/settings.json or a project's .claude/settings.json~/.codex/config.toml ([[hooks.<Event>]]) or ~/.codex/hooks.json, and the same in a project's .codex/
Example eventsSessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PermissionRequest, Notification, Stop, SubagentStop, SessionEndSessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, Stop, Interrupt, SessionEnd
Before a hook runsit runs once it's in settings (not in folders Claude doesn't trust yet, or with "disableAllHooks": true)you review and trust it with /hooks; Codex records trust against the hook's hash, so a changed hook needs trusting again

Both tools read their hooks when a session starts, so a new or changed hook takes effect in the next chat.

In Pairbar

Pairbar's live status installs hooks for Claude and Codex (Settings → Integrations, off until you install them). They run a small helper that passes only metadata (the chat's id, folder, event and a short tool summary such as "Bash · git push") over a private socket on your Mac, so a chat waiting for approval shows Needs you at once. Install backs up the file and adds only Pairbar's entries; Uninstall removes exactly them. See set up live status hooks.

Frequently asked questions

Are Claude Code hooks and Codex hooks the same?
They're the same idea with similar event names, but configured separately: Claude Code in settings.json, Codex in config.toml or hooks.json, and Codex runs a non-managed hook only after you trust it.
Can a hook slow the agent down?
Yes, a synchronous hook makes the agent wait for it. Claude Code can run a hook with "async": true so it carries on without waiting.
Why isn't my hook running?
Start a new session first. In Claude Code check the folder is trusted and disableAllHooks isn't set; in Codex trust the hook with /hooks and check hooks = false isn't set under [features].

Related