PI

Prerequisites

• Swamp installed
• Pi installed

Initialize the repository

$ swamp repo init --tool pi

You will see output like:

20:46:57.143 INF repo·init Initialized swamp repository at "/path/to/your/repo" (tool: "pi")

What this sets up

Swamp adds its rules and skill list to AGENTS.md, copies bundled skills to .pi/skills/, and installs an audit extension at .pi/extensions/swamp-audit.ts that records bash tool invocations via Pi's tool_call and tool_result events. Your own project instructions coexist in AGENTS.md via managed sections — Swamp only touches its own delimited block.

Use alongside another agent

Enroll multiple tools by repeating --tool on swamp repo init. Each tool's scaffolding is written independently, so AGENTS.md and another tool's instructions file (such as CLAUDE.md) coexist in the same repository.

$ swamp repo init --tool pi --tool claude

To enroll an additional tool in an existing repository, run swamp repo upgrade with the full intended list — upgrade replaces the enrolled tools, so any tool you want to keep must appear in the command:

$ swamp repo upgrade --tool pi --tool claude

Verify it works

Run Pi in your repository and invoke:

/skill:swamp-getting-started

The agent matches the getting-started skill and walks you through creating your first model.

Record and view agent commands

Every bash command Pi runs is appended to .swamp/audit/commands-YYYY-MM-DD.jsonl by the audit extension. View recent rows:

$ swamp audit --hours 1

Each row shows the command, cwd, timestamp, session ID, and success/failure.

To verify end-to-end, ask Pi to run a command like ls, then in another terminal run swamp audit --hours 1. You should see that command in the output.

Upgrading

When a new version of Swamp is released, upgrade the repository to get updated skills, instructions, and audit extension:

$ swamp repo upgrade

The managed section in AGENTS.md is replaced with the latest content. Anything you wrote outside the managed section is preserved. The audit extension is overwritten with the latest version.