CLAUDE CODE

Prerequisites

• Swamp installed
• Claude Code installed

Initialize the repository

Claude Code is the default tool, so no --tool flag is needed.

$ swamp repo init

You will see output like:

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

What this sets up

Swamp writes its rules and skill list to an instructions file, installs bundled skills in ~/.claude/skills/ in your home directory, and writes .claude/settings.local.json with permissions for Swamp CLI commands and an audit hook. Swamp only touches its own delimited managed section, so your own project instructions in the same file are preserved.

The audit hook runs swamp audit record --from-hook after each call of Claude Code's shell tools, with the matcher Bash|PowerShell. swamp repo upgrade widens a Bash-only entry an earlier version wrote. The permissions allow-list covers Bash(swamp ...) only, so Swamp calls through the PowerShell tool still ask for permission.

Claude Code reads .claude/settings.local.json from the git root (from the folder the session starts in on Windows, and before Claude Code 2.1.211). A repository nested below its git root, or a session started in a folder above the repository, does not run the repository's hook. To record those calls, add the hook to your user settings.

The instructions file depends on what the repository already has. The first match wins:

Swamp never writes through a symlinked CLAUDE.md, so a CLAUDE.md -> AGENTS.md link is left alone. Claude Code reads AGENTS.md only when no CLAUDE.md exists, and loads .claude/rules/ files alongside it, so writing the rules file keeps your AGENTS.md in use.

If CLAUDE.md holds only Swamp's managed section and AGENTS.md has your own content, Swamp adds an @AGENTS.md import inside the managed section so Claude Code still reads AGENTS.md.

If your .gitignore covers .claude/, the rules file stays out of version control. Teammates get it by running swamp repo upgrade.

Use alongside another agent

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

$ swamp repo init --tool claude --tool kiro

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 claude --tool kiro

Record calls from any folder

To record Swamp calls whatever folder a Claude Code session starts in, add the audit hook to your Claude Code user settings:

$ swamp audit install --user
✓ Added swamp's audit hook to /Users/you/.claude/settings.json
Claude Code now records Bash and PowerShell calls whose working directory is
inside a swamp repo, wherever the session started. The hook runs on every
such call in every project; calls run from outside a swamp repo are not
recorded.

The hook is written to settings.json in $CLAUDE_CONFIG_DIR when that is set, otherwise to ~/.claude/settings.json, and covers every repository. --user is required: the hook in a repository's .claude/settings.local.json is managed by swamp repo upgrade. Claude Code runs an identical hook from both files once, so a call is not recorded twice. See Use the Audit Timeline for which calls the user-level hook records.

To remove it:

$ swamp audit uninstall --user
✓ Removed swamp's audit hook from /Users/you/.claude/settings.json

Uninstall removes only entries Swamp added; a hook you wrote yourself is left in place.

Verify it works

Open Claude Code in your repository and run:

/swamp-getting-started

The agent loads the getting-started skill and walks you through creating your first behavior.

Upgrading

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

$ swamp repo upgrade

The managed section in the instructions file (CLAUDE.md or .claude/rules/swamp.md) is replaced with the latest content. Anything you wrote outside the managed section is preserved. Upgrade picks the file by the same rules as swamp repo init.