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.

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 models is not enough: the timeline's command lines can name models, 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.

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.