# A Claude Code audit log from what is already on disk

> By default Claude Code keeps 30 days of every tool call on disk. Read it back as an audit trail, add a hook or OpenTelemetry, and know the gaps.

Canonical: https://ranwhat.com/guides/claude-code-audit-log
Last updated: 2026-11-16

Something changed in your repository and nobody remembers running it. Before you install a logging hook, look at what Claude Code already wrote down: every tool call from the last 30 days, by default.

```
$ uvx ranwhat watch
```

[Install](https://ranwhat.com/install)

Checked against Claude Code's documentation, the advisories and research under Sources, and ranwhat's source. Published 2 October 2026, updated 16 November 2026.

## The record you already have

Claude Code saves each session to a transcript as you work. Its documentation describes the file as the full conversation: every message, every tool call and every tool result. That is an audit log in all but name, and it is already on your disk.

- **Where**: `~/.claude/projects/<project>/<session-id>.jsonl`, one JSON object per line. `<project>` is the working directory with every character that is not a letter or digit replaced by a hyphen, so `/Users/you/app` becomes `-Users-you-app`. With `CLAUDE_CONFIG_DIR` set, the whole tree lives under that directory instead.
- **What**: Anything that passes through a tool: each Bash command and its output, each file the Read tool opened and what it contained, each Edit, Write and MCP call. Large outputs are spilled to `<session>/tool-results/`, and subagents keep their own transcripts in `<session>/subagents/`.
- **How long**: **`cleanupPeriodDays`, 30 by default.** After a session starts, a background sweep deletes older transcripts without a message. A session you last used five weeks ago has no record unless you raised the setting before it aged out, or started or last continued it in Claude Desktop or Cowork: Claude Code v2.1.248 and later keep those at any age by default.
- **Prompts**: `~/.claude/history.jsonl` holds every prompt you typed, with a timestamp and the project path, and the sweep leaves it alone. It records what you asked for, not what ran.
- **Missing**: A session started with `CLAUDE_CODE_SKIP_PROMPT_HISTORY=1`, or a `claude -p` run with `--no-session-persistence`, writes no transcript at all.
- **Trust**: Plaintext, not encrypted at rest, and protected only by file permissions. Anything running as your user can edit or delete it. Treat it as evidence for yourself, not proof for a third party.

To keep more than a month, raise the setting in `~/.claude/settings.json`. The minimum is 1, and `0` fails validation rather than meaning forever. A higher value keeps what the sweep has not reached yet. It does not bring back what it already deleted.

```
$ ~/.claude/settings.json
{
  "cleanupPeriodDays": 365
}
```

### Look without installing anything

```
ls -lt ~/.claude/projects/*/*.jsonl | head      # newest sessions first
grep -lF -- 'git push --force' ~/.claude/projects/*/*.jsonl
claude --resume <session-id>                   # then /export to save it as text
```

The file name is the session ID. `grep` tells you which transcripts contain a string, not that the command ran: the same text turns up in a file the agent read, in a search pattern or in an `echo`. `/export` writes the conversation as plain text with tool output rendered, which reads better than raw JSON. Claude Code's documentation says the line format is internal and changes between versions, so any script that parses it can break on a release, ranwhat included.

### Is there a Claude Code activity log?

Not as a separate file. The closest thing to a Claude Code activity log is the transcript above: every tool call of every session, for as long as `cleanupPeriodDays` keeps it. `history.jsonl` adds the prompts, not what ran. To add audit logs to Claude Code going forward, use the [hook](https://ranwhat.com/guides/claude-code-audit-log#hook) below for a log file on this machine, or [OpenTelemetry](https://ranwhat.com/guides/claude-code-audit-log#otel) to send each tool call to a collector you run.

## Read it back with ranwhat watch

A month of transcripts is too long to read and mostly routine. [ranwhat watch](https://ranwhat.com/watch) reads them where they are and reports the calls worth a second look. No hook, no proxy, and it sends nothing anywhere.

```
$ uvx ranwhat watch --days 30
```

[Install](https://ranwhat.com/install)

`uvx` runs it without installing it. `--days 90` finds more if `cleanupPeriodDays` was already above 30, if a session you resumed within the retention period has older actions in it, or for sessions started or last continued in Claude Desktop or Cowork, which Claude Code v2.1.248 and later keep at any age by default.

The same command is an audit trail for more than Claude Code. By default it reads the history of Claude Code, Codex, Gemini CLI and twenty-seven more coding agents, and `--source ID` limits it to one.

### Sixteen rules

| Rule | Severity | For example |
| --- | --- | --- |
| **Credential access** | Critical | `cat ~/.aws/credentials`, Read on `.env` |
| **Secret-shaped string in a tool call** | Critical | `sk_live_…` `ghp_…` `AKIA…` |
| **Package or release published** | Critical | `npm publish` `twine upload` `docker push` |
| **Cloud resource destroyed or modified** | Critical | `terraform destroy` `kubectl delete` `aws iam attach-…` |
| **Financial API called** | Critical | Stripe charges, refunds, transfers or payouts |
| **Log or history tampering** | Critical | `history -c` `aws cloudtrail stop-logging` |
| **Cloud instance credentials requested** | Critical | `curl 169.254.169.254/…/iam/security-credentials/role` `…/service-accounts/default/token` |
| **Destructive git** | High | `git push --force` `git reset --hard` |
| **Recursive deletion** | High | `rm -rf ~/Documents/old-notes` `find . -delete` |
| **Local file sent to the network** | High | `curl -d @dump.sql` `curl -F file=@notes.txt` |
| **Downloaded script run unread** | High | `curl … \| sh` `bash <(curl …)` `iwr … \| iex` |
| **Files made writable by every user** | High | `chmod -R 777 /var/www` `chmod o+w config.ini` |
| **Container data wiped** | High | `docker system prune -a --volumes` `docker volume rm` `docker compose down -v` |
| **Decoded command run** | High | `echo … \| base64 -d \| sh` `eval "$(… \| base64 -d)"` `powershell -enc …` |
| **Startup or scheduled job installed** | High | `crontab -` `launchctl load …` `schtasks /create` |
| **Agent guardrails loosened** | High | `claude --dangerously-skip-permissions` `ranwhat hook uninstall` `"defaultMode": "bypassPermissions"` |

Severity follows the target, not the verb: `rm -rf build` is not reported, `rm -rf ~/Documents` is high and `rm -rf "$HOME"` is critical. In the same way `chmod 777 deploy/` is medium, a recursive change is high, and `chmod -R 777 /` is critical. An `export PATH` line appended to `~/.zshrc` is medium; one that runs `curl … | sh` in every new shell is high. An MCP server added to an agent's settings is medium, and an edit that takes the ranwhat hook out of them is critical. A command hidden in base64 is judged twice: as a decoded command run, and by the other rules on what it decodes.

### As a log you can keep

`ranwhat watch --json` prints one record per flagged call:

```
$ ranwhat watch --jsonone record
{
  "id": "5b0e93c1d7a24f68",
  "source": "claude-code",
  "session": "3f2a9c1e-0b7d-4e55-9a10-2c6e8d4b7f01",
  "project": "-Users-you-app",
  "cwd": "/Users/you/app",
  "timestamp": "2026-09-26T14:42:10.000Z",
  "tool_name": "Bash",
  "tool_call_id": "toolu_01",
  "payload_hash": "9006c7010e00d3a2",
  "severity": "high",
  "hits": [
    {
      "rule": "fs.destructive",
      "severity": "high",
      "title": "Bulk or recursive deletion",
      "why": "Recursive deletion. Recoverable only if something else was backing it up.",
      "evidence": "rm -rf ~/Documents/old-notes"
    }
  ]
}
```

```
ranwhat watch --json | jq -r '.[] | [.timestamp, .severity, .tool_name, .hits[0].evidence] | @tsv'
```

- **Once each**: A call replayed by a resumed session is reported once, not once per transcript that carries it.
- **Not actions**: `grep "rm -rf" src/` and other searches, `echo` and `printf` arguments, heredoc bodies, `python -c` and `node -e` payloads, comments, and `git rm --cached`. A `bash -c` payload is parsed, because it really is shell. A secret-shaped string is the exception: it is reported wherever it appeared verbatim in a tool call, including `echo` and `printf` arguments, heredoc bodies, `-c` or `-e` payloads and search patterns, because it is in the transcript either way.
- **Moved config**: When `CLAUDE_CONFIG_DIR` is set, ranwhat reads `$CLAUDE_CONFIG_DIR/projects` instead. `--root PATH` reads any other directory.
- **Nothing read**: The report's header counts the transcripts it read. A run that reads nothing says that nothing was checked, rather than that nothing was found. That almost always means the wrong directory or too short a window, not a clean history.
- **Not read yet**: The spilled outputs in `<session>/tool-results/`, and `history.jsonl`. Subagent transcripts in `<session>/subagents/` are read, and each call in them is credited to the session that started the subagent.
- **Call, not result**: watch judges each call as the agent made it. It does not read the result, so a call you refused or one that failed is reported the same way as one that ran. The result is in the transcript beside it, and the result before a call often explains it. In 0DIN's demonstration of 25 June 2026, Claude Code ran `python3 -m axiom init` because an error message told it to, and that command opened a reverse shell. watch does not flag it. When a session looks wrong, resume it, `/export` it, and read the result before each command.

## Log every command from now on with a hook

The transcript keeps everything for a month. For one line per command, kept as long as you like, Claude Code's hooks guide has a ready example.

```
$ ~/.claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/.claude/command-log.txt"
          }
        ]
      }
    ]
  }
}
```

In `~/.claude/settings.json` it covers every project on this machine. In a repository's `.claude/settings.json` it covers that project and can be committed. If the file already has a `hooks` key, merge into it. The command needs `jq` on your path, and `/hooks` lists what is registered.

The hook's input also carries `session_id`, `cwd` and `hook_event_name`. For one JSON line per command with a time on it, use this as the command instead:

```
jq -c '{time: (now | todate), event: .hook_event_name, session: .session_id, cwd: .cwd, command: .tool_input.command}' >> ~/.claude/command-log.jsonl
```

- **Failures**: **`PostToolUse` fires only after a tool call succeeds.** A command that exits non-zero fires `PostToolUseFailure` instead, so add the same entry under that event or the log misses every failed command. A call refused at the permission prompt fires neither; `PreToolUse` sees it.
- **Subagents**: Hooks fire inside subagents too, with an `agent_id` field in the input, so the log covers their commands as well.
- **transcript_path**: The input includes the session's transcript path. The transcript is written asynchronously and may not hold the current turn's latest messages when the hook fires, so log from the hook's own input rather than reading the file.
- **Off switch**: `"disableAllHooks": true` in any settings file other than managed settings turns off user, project, local and plugin hooks, and a project's settings take precedence over yours. Hooks in managed settings keep running; yours do not.
- **Same weakness**: The log is a plaintext file on the same machine. It is not on the retention sweep's list, so it grows until you rotate it, and anything running as you can edit it.

## Send it to your own collector

A hook writes to this machine. OpenTelemetry sends events to a collector you run, as they happen. Claude Code's monitoring documentation calls these events the audit data source for Claude Code activity.

```
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_LOG_TOOL_DETAILS=1
claude
```

- **Events**: Each tool call that runs produces a `claude_code.tool_result` event with `tool_name`, `success` and `duration_ms`. A refused call produces a `tool_decision` event with `decision` set to `reject`. Both carry the `tool_use_id` that hooks receive, so the two records can be joined.
- **The gate**: **Without `OTEL_LOG_TOOL_DETAILS=1`, neither the Bash command nor the tool input is logged.** With it, `tool_parameters` carries the full command, and `tool_input` the arguments, with values over 512 characters truncated and the whole bounded to about 4K characters.
- **Output**: `OTEL_LOG_TOOL_CONTENT=1` adds what the tool returned, such as file contents and command output, as a `tool.output` span event, truncated at 60 KB by default. It needs tracing: `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1` and `OTEL_TRACES_EXPORTER`.
- **Defaults**: Export is opt-in, and both `OTEL_LOG_TOOL_DETAILS` and `OTEL_LOG_TOOL_CONTENT` are off by default. The data goes only to the endpoint you configure, never to Anthropic. Commands can carry secrets, so filter at the collector if they will be stored.
- **Repositories**: A repository's `.claude/settings.json` cannot turn telemetry on or send it elsewhere, but it can set `OTEL_LOGS_EXPORTER` to `none`, unless that variable comes from managed settings, a `--settings` file or the shell you start `claude` from. Export it in the shell.
- **Nothing arrives**: Submit a prompt and look for `claude_code.user_prompt`. If it is not there, start with `claude --debug-file <path>` and look for `[3P telemetry]` errors. Claude Code emits the raw events only; alerting is the collector's job.

## Which one to use

| Record | Covers | Lives | Watch for |
| --- | --- | --- | --- |
| **Transcript** | Already there: the last 30 days, or `cleanupPeriodDays` | Local plaintext, editable by anything running as you | Silent deletion after the period; a format that changes between versions |
| **Hook** | From the moment you add it, for as long as you keep the file | A local file you define | Failed commands unless you add `PostToolUseFailure`; `disableAllHooks` in a project |
| **OpenTelemetry** | From the moment you enable it, for as long as your backend keeps it | Off the machine, at your collector | Only what the gates allow: no commands without `OTEL_LOG_TOOL_DETAILS=1` |

Most people want the first today and one of the other two going forward. Run `uvx ranwhat watch --days 30` over what is on disk now. Then add the hook if the record can stay on this machine, or OpenTelemetry if it has to leave it, where a later edit here cannot reach it.

### A policy is not a record

Settings say what should happen. The transcript says what did. Before 2.1.260, a Claude Code session signed in to a Team or Enterprise account fetched the organisation's server-managed settings with an API key it had stored earlier, from a past `/login` or written into its config. When the settings endpoint rejected that key, the session still ran as the organisation's account, but with none of its server-managed policy (no deny rules, model restrictions or managed-only locks), or with a stale cached copy (CVE-2026-103012, published 29 September 2026). Enterprise was affected from 2.0.68 and Team from 2.1.38. MDM and file-based managed settings were not.

```
claude --version               # 2.1.260 or later
/permissions                   # the organisation's rules should be listed
uvx ranwhat watch --days 30    # what ran while they may not have applied
```

watch reads only what retention kept, and a session nobody used within `cleanupPeriodDays` is already gone. Administrators can set `requiredMinimumVersion` to 2.1.260 through MDM or a managed settings file.

Nor does the transcript record a change to the configuration itself. Mitiga showed an npm `postinstall` script marking common clone paths as trusted in `~/.claude.json`, after which a hook in a repository cloned there re-pointed an OAuth MCP server at a proxy on localhost at every start, and read each token that passed. Anthropic ruled it out of scope, Mitiga reports, because the chain depends on consent the user has already given. Mitiga's advice is to watch `~/.claude.json` and a project's MCP files for changes, and to keep a list of the MCP endpoints you approved. Hooks deserve the same watch: `/hooks` lists what is registered.

## When the log shows a deletion

An `rm -rf` in the record tells you what ran. Whether the files can come back is a separate question, and checkpoints will not answer it: Claude Code's checkpointing does not track files changed by Bash commands. Start with the guide to [files Claude Code deleted](https://ranwhat.com/guides/claude-code-deleted-files). For everything else Claude Code keeps on disk, read the [Claude Code history guide](https://ranwhat.com/guides/claude-code-history); for the controls around all of this, the [AI coding agent security checklist](https://ranwhat.com/guides/ai-coding-agent-security). [ranwhat watch](https://ranwhat.com/watch) has the full rule set, and the rest of the [guides](https://ranwhat.com/guides) are listed here.

## Common questions about a Claude Code audit log

### Does Claude Code have an audit log?

Not under that name, but each session's transcript records every tool call and its result, so the last 30 days are already on disk by default.

### What is cleanupperioddays?

The Claude Code setting that decides how long those transcripts are kept: 30 days by default, minimum 1. Raise it before you need the record. [cleanupPeriodDays](https://ranwhat.com/guides/claude-code-cleanupperioddays) explains it in full.

### How do I log every command Claude Code runs from now on?

Add a PostToolUse hook that appends each call to a file, or export OpenTelemetry to your own collector. Both are in the sections above.

### Which tools read Claude Code's audit trail?

`uvx ranwhat watch` reads the transcripts already there. [Audit log tools compared](https://ranwhat.com/guides/claude-code-audit-log-tools) puts it beside suvadu and cc-audit-log.

## Sources

- [Explore the .claude directorytranscript contents, retention sweep, Desktop and Cowork transcripts, plaintext storage](https://code.claude.com/docs/en/claude-directory#application-data)
- [Settings reference: cleanupPeriodDaysdefault, minimum, the sweep](https://code.claude.com/docs/en/settings-reference#cleanupperioddays)
- [Manage sessionstranscript location, format, export](https://code.claude.com/docs/en/sessions#where-transcripts-are-stored)
- [Environment variablesCLAUDE_CONFIG_DIR, CLAUDE_CODE_SKIP_PROMPT_HISTORY](https://code.claude.com/docs/en/env-vars)
- [Hooks guidethe command-log example, hook locations](https://code.claude.com/docs/en/hooks-guide)
- [Hooks referenceinput fields, PostToolUseFailure, disableAllHooks](https://code.claude.com/docs/en/hooks)
- [Monitoring usageOpenTelemetry events and gates](https://code.claude.com/docs/en/monitoring-usage)
- [CheckpointingBash changes are not tracked](https://code.claude.com/docs/en/checkpointing)
- [Settings reference: requiredMinimumVersionmanaged only, 2.1.163 or later](https://code.claude.com/docs/en/settings-reference#requiredminimumversion)
- [GHSA-gfvf-j8jh-jxxwCVE-2026-103012, fixed in 2.1.260](https://github.com/anthropics/claude-code/security/advisories/GHSA-gfvf-j8jh-jxxw)
- [0DIN: Clone this repo and I own your machinethe error Claude followed](https://0din.ai/blog/clone-this-repo-and-i-own-your-machine)
- [Mitiga: stealing MCP tokens in Claude Codethe chain, the disclosure, what to watch](https://www.mitiga.io/blog/claude-code-mcp-token-theft-mitm)
- [ranwhat/watch.pythe sixteen rules and the JSON record](https://github.com/MatijaMiki/ranwhat/blob/main/ranwhat/watch.py)
- [ranwhat referencewhat is not treated as an action, what is not read](https://github.com/MatijaMiki/ranwhat/blob/main/docs/reference.md#precision-is-the-feature)

## Related guides

- [All guideseverything in this section](https://ranwhat.com/guides)
