What is a Claude Code hook?
A hook is a command registered for an event, such as a prompt being submitted, a tool being used, or a session ending. Claude Code reads the registration from its settings file and runs the command, passing the details of the event. Hooks do not change what the agent does; they only run beside it. The hooks reference lists every event and what each one receives.
Which events matter for an audit log?
Four events are enough to rebuild a session: the prompt that started it, each edit or command, the end of a turn, and the end of the session.
UserPromptSubmitgives you the prompt, which is the “who asked for what”.PostToolUseruns after the agent edits a file or runs a command, which tells you what changed.Stopmarks the end of a turn.SessionEndis the moment to turn the events into one entry.
What does the setup look like?
Running agentreceipt init merges the hooks below into .claude/settings.json without removing yours. This is the configuration it wrote in a test repository. Each hook calls agentreceipt record with the event name, and the tool reads the details Claude Code passes in.
npm install -g @agent-receipt/cli cd your-repo agentreceipt init # merged into .claude/settings.json: "UserPromptSubmit" -> agentreceipt record UserPromptSubmit "PostToolUse" -> agentreceipt record PostToolUse (matcher: Edit|Write|MultiEdit|Bash) "Stop" -> agentreceipt record Stop "SessionEnd" -> agentreceipt record SessionEnd
What ends up in the log?
When the session ends, agentreceipt finalize builds one receipt: the prompt, every file that changed with its lines added and removed, and a list of flags from fixed rules. Secret-like values are replaced before anything is written to disk. Read it with agentreceipt show.
agentreceipt finalize agentreceipt show
How is this different from monitoring or an organization-wide API?
Anthropic documents ways to monitor Claude Code usage and a Compliance API for organizations. Those describe activity across accounts and tools. A hook-based log is different: it lives in your repository, it is tied to your commits, and it records the diff, not just that a session took place.
They answer different questions, so they can be used together. Read each vendor document for exactly what it covers, because that changes over time.
What are the limits?
A hook log is written on the developer’s machine, so it is self-reported. If someone turns the hooks off, no entries are written, and a missing entry proves nothing about how code was written. Store entries as git notes and check for missing ones in review if that matters to you.