How to keep an audit log of Claude Code sessions

By the AgentReceipt team · Updated 16 November 2026

Claude Code can run a command of your choosing when events happen in a session. That makes hooks the most direct way to build an audit log of what it was asked and what it changed. This guide shows the hook setup, what to log, and where other options fit.

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.

  • UserPromptSubmit gives you the prompt, which is the “who asked for what”.
  • PostToolUse runs after the agent edits a file or runs a command, which tells you what changed.
  • Stop marks the end of a turn.
  • SessionEnd is 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.

Sources and further reading