THE AUDIT SYSTEM

When an AI agent operates a Swamp repo, it runs dozens of commands in minutes. Some are swamp commands. Some are direct CLI calls to tools like aws, terraform, or kubectl. The human who returns to the repo needs a single answer: what happened while I was away? The audit system exists to provide that answer — a chronological timeline of every command, regardless of origin.

Two sources of truth

Swamp commands are recorded automatically. Every swamp model method run, swamp workflow run, or swamp data query invocation writes an audit entry with a timestamp, session ID, and the full command string. No configuration required.

Direct CLI commands are a harder problem. A Swamp workflow might run swamp model method run deploy, but the model's method internally calls aws ec2 run-instances. Without capturing that second command, the audit timeline has a gap. Audit hooks close the gap by recording CLI commands executed within the repo directory. The result is a unified timeline where both layers are visible: the Swamp command that initiated the work and the underlying tool invocations it produced.

Why hooks are tool-specific

Each AI coding tool intercepts shell commands through a different mechanism. Claude Code uses hooks defined in its settings file. Cursor uses shell integration. Other tools have their own extension points. A single generic approach would miss commands or double-count them depending on the tool's execution model.

swamp repo init --tool <tool> configures the correct hook for the active tool. swamp doctor audit verifies the hook is installed and functioning. The tradeoff is explicit: rather than attempting a fragile universal solution, Swamp maintains per-tool integrations that each work reliably.

Sessions isolate concurrent actors

Each terminal session or agent run receives a session ID. The audit timeline can be filtered by session, which matters when multiple agents or humans work in the same repo at the same time. Without session filtering, interleaved commands from different actors would produce an unreadable timeline. With it, you can isolate exactly what one agent did during one run.

What audit deliberately omits

The audit system records commands, not outcomes. It does not capture exit codes, stdout, stderr, or which resources a command created or destroyed. This is a deliberate design boundary. Recording outcomes would require parsing tool-specific output formats, handling streaming output, and storing potentially large payloads — all of which would make the system expensive and fragile.

For execution outcomes, Swamp has purpose-built tools: swamp model method history shows what a method produced, and swamp workflow history shows the result of each workflow step. The audit timeline complements these by answering a different question: not "what was the result?" but "what was attempted?"

This separation keeps audit lightweight and always-on. Every command is recorded with minimal overhead, so the timeline is never incomplete. The more expensive work of tracking outcomes stays in the systems that already do it well.

For a broader view of how these primitives compose, see How Swamp Works.