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 auditThe 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 4Include all commands
By default, noise commands like ls and cat are filtered out. To see
everything:
swamp audit --allFilter 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.comOn 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:auditTo 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:auditThen reloads the policy:
swamp access reload --server wss://swamp.example.comTo create the same grant without a file:
swamp access grant create --subject user:reader --allow admin --on access:audit --server wss://swamp.example.comRefer 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: PASSIf 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 whoamiSign 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.