Skip to main content

KIRO

Prerequisites

Initialize the repository

$ swamp repo init --tool kiro

You will see output like:

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

What this sets up

Swamp writes four files to the repository and installs its bundled skills (swamp and swamp-getting-started) in ~/.kiro/skills/ in your home directory.

IDE-facing (Kiro IDE):

  • .kiro/steering/swamp-rules.md — steering file with Swamp rules.
  • .kiro/hooks/swamp-audit.json — a Kiro v1 hook (PostToolUse) that records shell commands via swamp audit record --from-hook --tool kiro. Kiro IDE 1.0 runs it.

CLI-facing (kiro-cli):

  • .kiro/agents/swamp.json — agent config. Declares skill resources, an explicit tool list (glob, grep, read, shell, thinking, todo_list, write), and the audit hook as an array entry. It pre-approves swamp commands and blocks swamp vault read-secret, with both the 2.x toolsSettings and the 3.0 permissions.rules. The file is in kiro-cli's universal format, so both the default 2.x engine and the opt-in 3.0 engine (kiro-cli --v3) load it.
  • .kiro/settings/cli.json — sets chat.defaultAgent to swamp so plain kiro-cli chat loads the Swamp agent and the audit hook runs.

Kiro IDE ignores agent configs that contain hooks, so the Swamp agent applies to kiro-cli only.

Pre-approve Swamp commands in Kiro IDE

Kiro IDE 1.0 reads permission rules only from outside the repository, so Swamp cannot write them for you. To run Swamp commands without a prompt, choose Always allow for the workspace when Kiro asks, or add a rule to ~/.kiro/settings/permissions.yaml:

rules:
  - capability: shell
    match: ["swamp *"]
    exclude: ["*read-secret*"]
    effect: allow

The exclude keeps swamp vault read-secret behind a prompt. See Kiro permissions for the rule format.

Use alongside another agent

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

$ swamp repo init --tool kiro --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 kiro --tool claude

Verify it works

In Kiro IDE, select swamp-getting-started from the / skills menu.

In kiro-cli, type:

I am new to swamp

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

Record and view agent commands

Every shell command the agent runs in Kiro IDE, or the Swamp agent runs through kiro-cli chat, is appended to .swamp/audit/commands-YYYY-MM-DD.jsonl by the audit hook. View recent rows:

$ swamp audit --hours 1

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

To verify end-to-end, run something like docker ps in kiro-cli chat, then in another terminal run swamp audit --hours 1. You should see that command in the output.

Under the opt-in kiro-cli 3.0 engine, both the agent's hook and .kiro/hooks/swamp-audit.json run, so a shell command may appear twice in swamp audit.

If you already use a custom kiro-cli default agent

If .kiro/settings/cli.json already sets chat.defaultAgent to something other than swamp, Swamp leaves it alone and logs a warning at init. Your preference wins, but the audit hook will not run through the default agent. To record agent commands, either:

  • change chat.defaultAgent to swamp in .kiro/settings/cli.json, or
  • invoke kiro-cli chat --agent swamp explicitly.

Upgrading

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

$ swamp repo upgrade

The steering file, agent config, and .kiro/hooks/swamp-audit.json are overwritten with the latest versions. .kiro/settings/cli.json is merged to preserve any keys you added.

Upgrade also removes what earlier versions of Swamp wrote for Kiro IDE 0.x:

  • It deletes Swamp's legacy .kiro/hooks/swamp-audit.kiro.hook, and removes copies of the audit hook that Kiro IDE auto-migrated into other .kiro/hooks/*.json files. Only Swamp's exact hook entry is removed — a hook whose command you extended is kept — and a file is deleted only if nothing else is left in it.
  • It removes Swamp's own entries (swamp * and read-secret) from .vscode/settings.local.json, keeping your entries and other settings, and deletes the file only if nothing is left in it.
← PreviousCursorNext →OpenCode