Skip to main content

USE THE AUDIT TIMELINE

Prerequisites: Swamp installed, a repository with the audit hook enabled. If swamp audit reports no data, run swamp repo init --force to enable the audit hook.

If the repository sits below its git root, or your Claude Code sessions start in a folder above it, the repository's own hook does not run. Run swamp audit install --user to add the hook to your Claude Code user settings (see Claude Code). With the user-level hook, a call is recorded when its working directory is inside a Swamp repository. A call run from above the repository is not recorded: a cd inside a subshell, or --repo-dir, leaves the call's working directory outside it. The user-level hook starts a Swamp process for every Bash and PowerShell call in every project, about 0.45 seconds each.

View the default timeline

The audit timeline shows Swamp commands from the last 24 hours:

swamp audit

The output groups commands by session and shows timestamps, commands, and whether they were run through Swamp or directly.

Change the time window

To narrow the window to the last 4 hours:

swamp audit --hours 4

Include all commands

By default, noise commands like ls and cat are filtered out. To see everything:

swamp audit --all

Filter by session

If you know the session ID you want to inspect:

swamp audit --session <session-id>

View the timeline on a server

To read the timeline from a swamp serve instance instead of the local repository:

swamp audit --server wss://swamp.example.com

On a server with authentication enabled, this needs admin on access:audit, the same as the server's other audit commands. A read grant on behaviors is not enough: the timeline's command lines can name behaviors, workflows and vaults that a deny grant hides from you. Without the grant, the server refuses the request:

Error: Server reported unauthorized: Access denied: user:reader does not have 'admin' on access:audit

To give an operative access, an admin adds a grant file to the server's grants/ directory:

# grants/audit-viewers.yaml
grants:
  - subject: user:reader
    effect: allow
    actions: [admin]
    resource: access:audit

Then reloads the policy:

swamp access reload --server wss://swamp.example.com

To create the same grant without a file:

swamp access grant create --subject user:reader --allow admin --on access:audit --server wss://swamp.example.com

Refer to Authorization for how grants are evaluated, and Manage Grants with Files for the grant file format.

Check audit hook health

To verify the audit hook is installed and working:

swamp doctor audit
✓ binary-on-path  swamp is on PATH at /Users/you/.local/bin/swamp
✓ agent-config-loadable  .claude/settings.local.json is present with both PostToolUse hooks wired
✓ recording-smoke-test  synthetic payload landed in today's audit JSONL

4 passed, 0 failed, 1 skipped — OVERALL: PASS

If any check fails, swamp doctor audit describes what to fix. A check marked ! passed with a warning; the command still exits 0. For example, a repository nested below its git root:

! agent-config-loadable  /path/to/gitroot/infra/ops/.claude/settings.local.json is present with both PostToolUse hooks wired
    warning: this repo is below the git root /path/to/gitroot, and Claude Code reads .claude/settings.local.json from the git root, so this repo's audit hook does not fire for sessions started there
    hint: Run `swamp audit install --user` to add the audit hook to your Claude Code user settings; it records calls run inside any swamp repo.

See the Doctor reference for every check.

The timeline stopped filling

The audit hook records nothing when the account check blocks it, and it exits 0 so the agent session carries on. An empty or stalled timeline therefore usually means the check is blocking the hook: no credential, or no locally valid proof. The hook never calls swamp-club.com.

To see the reason, run any Swamp command in the same environment:

swamp auth whoami

Sign in, or set the credential the block message names. After a signed-in user's next ordinary command refreshes the proof, the hook records again.