What's Changed

• fix: correct Kiro hook format and add USER_PROMPT env var support (#584)

Summary

Fixes #581 — Kiro IDE does not recognize the swamp audit hook due to three issues, all addressed in this PR.

1. Hook file format

• Wrong extension: Kiro expects .kiro.hook, not .json — renamed swamp-audit.json → swamp-audit.kiro.hook
• Missing toolTypes: Kiro requires toolTypes: ["*"] in the when property — added
• No timeout: Added timeout: 5 to the then property to prevent hangs as a safety net

2. Input mechanism — USER_PROMPT env var

Kiro IDE passes postToolUse data via the USER_PROMPT environment variable, not stdin. The audit record command was blocking on readStdin() which caused timeouts. The fix:

• For --tool kiro: check USER_PROMPT env var first, fall back to stdin (preserving kiro-cli compatibility)
• The Kiro IDE format uses camelCase keys (toolName, toolArgs, toolResult, toolSuccess) which differs from the kiro-cli snake_case format

3. Dual-format normalizer

Updated normalizeKiro() to handle both:

• kiro-cli (stdin, snake_case): tool_name, tool_input, tool_response
• Kiro IDE (USER_PROMPT, camelCase): toolName, toolArgs, toolResult, toolSuccess

4. Upgrade cleanup

swamp repo upgrade --tool kiro now removes the old swamp-audit.json file so stale hooks don't linger.

Open question for @danmcclain

The USER_PROMPT env var format is based on Kiro's own description of its postToolUse data. Two things we'd appreciate verification on:

1. Is USER_PROMPT valid JSON? We parse it with JSON.parse() — if it's a different format, the hook will silently no-op (safe but won't record).
2. Does toolArgs contain { command: "..." } for execute_bash tools? You noted it "appears to be empty {}" in your examples — if that's always the case, we won't be able to extract the command. Could you verify with your test hook on an execute_bash invocation?

Files changed

Test plan

• deno check passes
• deno lint passes
• deno fmt passes
• deno run test — 2605 tests pass (4 new)
• deno run compile — binary builds
• Manual test: swamp repo init --tool kiro creates swamp-audit.kiro.hook with correct format
• @danmcclain to verify with Kiro IDE that the hook appears and USER_PROMPT format works

🤖 Generated with Claude Code

Installation

macOS (Apple Silicon):

curl -L https://github.com/systeminit/swamp/releases/download/v20260303.151256.0-sha.471cac05/swamp-darwin-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

macOS (Intel):

curl -L https://github.com/systeminit/swamp/releases/download/v20260303.151256.0-sha.471cac05/swamp-darwin-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (x86_64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260303.151256.0-sha.471cac05/swamp-linux-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (aarch64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260303.151256.0-sha.471cac05/swamp-linux-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

What's Changed

• fix: improve update/upgrade output and init error message (#585)

Summary

• Enrich swamp update log output with "updated globally" and "run swamp repo upgrade" hints after a successful update
• Enrich swamp repo upgrade log output to show what changed: skills, instructions, settings, and .gitignore status
• Improve swamp repo init error when already initialized to show current tool and suggest swamp repo upgrade -t <tool>

Fixes #583

Output examples

swamp repo init (already initialized):

14:32:20 FTL error Error: 'Repository already initialized at /private/tmp/swamp-output-test (tool: "claude"). To switch tools, run: swamp repo upgrade -t <tool>. To reinitialize from scratch, run: swamp repo --force -t <tool>'

swamp repo upgrade -t claude (same tool, nothing changed):

14:32:21 INF repo Upgraded swamp repository: "20260206.200442.0" → "20260206.200442.0" (tool: "claude")
14:32:21 INF repo   Skills updated: swamp-data, swamp-model, swamp-repo, swamp-workflow, swamp-extension-model, swamp-vault, swamp-issue, swamp-troubleshooting
14:32:21 INF repo   Instructions: unchanged
14:32:21 INF repo   Settings: unchanged
14:32:21 INF repo   .gitignore: unchanged

swamp repo upgrade -t cursor (switching tools):

14:32:22 INF repo Upgraded swamp repository: "20260206.200442.0" → "20260206.200442.0" (tool: "cursor")
14:32:22 INF repo   Skills updated: swamp-data, swamp-model, swamp-repo, swamp-workflow, swamp-extension-model, swamp-vault, swamp-issue, swamp-troubleshooting
14:32:22 INF repo   Instructions: updated
14:32:22 INF repo   Settings: updated
14:32:22 INF repo   .gitignore: updated

swamp update (updated case — from test output):

14:33:14 INF update swamp updated successfully!
14:33:14 INF update "20260207..." → "20260208..."
14:33:14 INF update SHA-256 integrity check passed
14:33:14 INF update The swamp binary has been updated globally.
14:33:14 INF update Run `swamp repo upgrade` in your repositories to update skills and settings.

Test plan

• deno check — type checking passes
• deno lint — no lint errors
• deno fmt — formatting correct
• deno run test — all 260 tests pass
• deno run compile — binary recompiles
• Tested compiled binary output in /tmp directory for all three scenarios

🤖 Generated with Claude Code

Co-authored-by: Walter Heck walterheck@helixiora.com

Installation

macOS (Apple Silicon):

curl -L https://github.com/systeminit/swamp/releases/download/v20260303.145336.0-sha.fcbb0957/swamp-darwin-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

macOS (Intel):

curl -L https://github.com/systeminit/swamp/releases/download/v20260303.145336.0-sha.fcbb0957/swamp-darwin-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (x86_64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260303.145336.0-sha.fcbb0957/swamp-linux-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (aarch64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260303.145336.0-sha.fcbb0957/swamp-linux-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

What's Changed

• fix: switch API token auth from Bearer to x-api-key header (#582)

Summary

• Switch all API key authentication from Authorization: Bearer to x-api-key header, reserving Bearer exclusively for the createApiKey call during login (session token auth)
• Reorder login flow to create the API key first, then verify identity with whoami using the new API key
• Update ExtensionApiClient, HttpTelemetrySender, and all related tests

Fixes #577

Test Plan

• All 2586 existing tests pass
• swamp_club_client_test.ts: Verifies whoami sends x-api-key header
• extension_api_client_test.ts: Verifies yank sends x-api-key header
• http_telemetry_sender_test.ts: Verifies telemetry sends x-api-key header
• deno check, deno lint, deno fmt --check all pass
• deno run compile succeeds

🤖 Generated with Claude Code

Installation

macOS (Apple Silicon):

curl -L https://github.com/systeminit/swamp/releases/download/v20260303.045025.0-sha.aab4626d/swamp-darwin-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

macOS (Intel):

curl -L https://github.com/systeminit/swamp/releases/download/v20260303.045025.0-sha.aab4626d/swamp-darwin-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (x86_64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260303.045025.0-sha.aab4626d/swamp-linux-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (aarch64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260303.045025.0-sha.aab4626d/swamp-linux-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

What's Changed

• fix: always create .gitignore on repo init (#580)

Summary

• swamp repo init now always creates/manages a .gitignore with the swamp managed section, instead of requiring the --include-gitignore flag
• If no .gitignore exists, one is created; if one already exists, the managed section is appended while preserving user content
• The --include-gitignore flag is removed from the init command but remains on repo upgrade for opt-in/opt-out control
• The gitignoreManaged: true marker is always set on init so subsequent upgrades continue managing the section

Behavior Change

Without this fix, users could accidentally commit sensitive files like .swamp/secrets/keyfile.

Test Plan

• All 64 unit tests in repo_service_test.ts pass (updated to reflect new behavior)
• Manual testing with compiled binary across 5 scenarios:
  1. Fresh init with no existing .gitignore — file created with managed section
  2. Init with existing user .gitignore — user content preserved, managed section appended
  3. Init with non-claude tool (cursor) — tool-specific entry (.cursor/skills/) included
  4. Upgrade after init — .gitignore maintained via marker
  5. Force re-init — .gitignore stays unchanged
• Full test suite passes (2585 tests)
• deno check, deno lint, deno fmt all pass

🤖 Generated with Claude Code

Installation

macOS (Apple Silicon):

curl -L https://github.com/systeminit/swamp/releases/download/v20260303.030136.0-sha.832572e4/swamp-darwin-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

macOS (Intel):

curl -L https://github.com/systeminit/swamp/releases/download/v20260303.030136.0-sha.832572e4/swamp-darwin-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (x86_64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260303.030136.0-sha.832572e4/swamp-linux-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (aarch64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260303.030136.0-sha.832572e4/swamp-linux-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

What's Changed

• feat: send content metadata during extension push (#579)

Summary

• During extension push, extract metadata from model .ts files and workflow .yaml files already in memory
• Send the extracted contentMetadata to the registry in the confirm-push request
• The server can now index extension contents (methods, arguments, resources, files, workflow structure) without re-parsing the uploaded archive

User impact

No user-facing behavior changes. The metadata extraction runs silently during push — results are logged at debug level only (visible with --verbose or SWAMP_LOG=debug). If extraction fails for any reason, push continues normally without metadata. The registry gains richer indexing data to power future extension search and discovery features.

Design

Why client-side extraction? The CLI already has all source files in memory at push time. Extracting metadata here avoids redundant server-side archive unpacking and parsing, reducing registry latency and complexity.

Why regex-based for models? Model .ts files follow well-defined patterns (ModelType.create(...), methods: { name: { description: ... } }, z.object({...})). Regex extraction matches the approach used by the swamp-club server (PR #145) and avoids needing to evaluate TypeScript. Balanced brace/paren matching handles nested structures like z.record(z.string(), z.string()).

Why YAML parsing for workflows? Workflow files are YAML — a proper parser (@std/yaml, already a dependency) gives exact results with no regex fragility.

Non-fatal by design. Every extraction is wrapped in try/catch at the per-file level. A single unparseable model or workflow is silently skipped, returning partial results. The top-level call is also wrapped, so even a catastrophic extractor bug cannot break extension push.

Changes

Test plan

• deno check — type checking passes
• deno lint — linting passes
• deno fmt — formatting passes
• deno run test — 2601 tests pass (15 new + 2586 existing)
• deno run compile — binary compiles
• Validated against real shell_model.ts — correctly extracts type, version, methods with arguments, resources, and files
• Manual: swamp extension push --dry-run on an extension with models and workflows

🤖 Generated with Claude Code

Installation

macOS (Apple Silicon):

curl -L https://github.com/systeminit/swamp/releases/download/v20260303.025753.0-sha.26137995/swamp-darwin-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

macOS (Intel):

curl -L https://github.com/systeminit/swamp/releases/download/v20260303.025753.0-sha.26137995/swamp-darwin-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (x86_64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260303.025753.0-sha.26137995/swamp-linux-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (aarch64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260303.025753.0-sha.26137995/swamp-linux-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

What's Changed

• fix: use absolute path for swamp binary in kiro hooks (#574)

Summary

• Kiro-cli does not perform PATH resolution when executing hook commands, causing No such file or directory (os error 2) errors when the swamp audit record hook fires
• Resolve the absolute path to the swamp binary at init/upgrade time using which and embed it in the kiro hook configuration
• Falls back to bare swamp if resolution fails
• Only affects kiro hooks — Claude, Cursor, and OpenCode handle PATH correctly

Test plan

• All 63 repo_service tests pass
• deno check passes
• deno lint passes
• deno fmt passes
• Manual: swamp repo init --tool kiro then verify .kiro/hooks/swamp-audit.json contains absolute path
• Manual: start kiro-cli and confirm audit hook no longer errors

🤖 Generated with Claude Code

Installation

macOS (Apple Silicon):

curl -L https://github.com/systeminit/swamp/releases/download/v20260303.011043.0-sha.990678e2/swamp-darwin-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

macOS (Intel):

curl -L https://github.com/systeminit/swamp/releases/download/v20260303.011043.0-sha.990678e2/swamp-darwin-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (x86_64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260303.011043.0-sha.990678e2/swamp-linux-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (aarch64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260303.011043.0-sha.990678e2/swamp-linux-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

What's Changed

• feat: add swamp extension yank command (#575)

Summary

• Add swamp extension yank <extension> [version] --reason <reason> command for yanking extensions from the registry
• Extension owners can yank their own extensions, admins can yank any extension (authorization enforced server-side)
• Add yankExtension() method to ExtensionApiClient calling POST /api/v1/extensions/{name}/yank and POST /api/v1/extensions/{name}@{version}/yank

Server-side implementation: https://github.com/systeminit/swamp-club/pull/158
Closes #571

Test plan

• deno fmt --check — formatting clean
• deno lint — linting clean
• deno check — type checking clean
• deno run test — 2512 tests pass, 0 failures
• deno run compile — binary recompiled
• API client tests: POST to correct endpoints (version/extension), auth header, request body, 410 already-yanked error, connection failure
• Output rendering tests: JSON mode with/without version, cancellation output
• Manual test against live registry after swamp-club#158 merges

🤖 Generated with Claude Code

Installation

macOS (Apple Silicon):

curl -L https://github.com/systeminit/swamp/releases/download/v20260303.005604.0-sha.bab2b48f/swamp-darwin-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

macOS (Intel):

curl -L https://github.com/systeminit/swamp/releases/download/v20260303.005604.0-sha.bab2b48f/swamp-darwin-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (x86_64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260303.005604.0-sha.bab2b48f/swamp-linux-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (aarch64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260303.005604.0-sha.bab2b48f/swamp-linux-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

What's Changed

• fix: swamp repo upgrade overwrites managed instructions file (#573)

Summary

• swamp repo upgrade now overwrites the instructions file (CLAUDE.md, .cursor/rules/swamp.mdc, etc.) when content has changed, keeping it in sync with swamp's template
• Adds updateInstructionsFile method using the existing overwriteIfChanged helper
• Adds instructionsUpdated field to RepoUpgradeResult and output types
• Refactors init/upgrade tool dispatch from if/else chains to exhaustive switch statements with assertNever
• Extracts shared createFileIfNotExists and overwriteIfChanged helpers, eliminating duplicated file-creation logic across tool-specific methods

Test plan

• Updated test asserting upgrade now overwrites stale instructions content
• Added test asserting instructionsUpdated: false when content is already current
• All 63 repo_service tests pass
• deno check passes
• deno lint passes
• deno fmt passes

🤖 Generated with Claude Code

Installation

macOS (Apple Silicon):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.235049.0-sha.05292a33/swamp-darwin-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

macOS (Intel):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.235049.0-sha.05292a33/swamp-darwin-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (x86_64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.235049.0-sha.05292a33/swamp-linux-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (aarch64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.235049.0-sha.05292a33/swamp-linux-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

What's Changed

• feat: add swamp audit command for tracking AI agent actions (#572)

Summary

Introduces swamp audit — a new command that captures every bash tool invocation from AI coding agents via PostToolUse hooks, providing visibility into which commands were run through swamp's managed workflow versus executed directly by the agent.

• Multi-tool support: Works with Claude Code, Cursor, Kiro, and OpenCode. Each tool has its own hook mechanism; a normalization layer (hook_input.ts) handles payload differences. Codex is unsupported (no per-command hooks) and shows a warning.
• Hook-based capture: swamp repo init --tool <tool> generates tool-specific hook configs (.claude/settings.local.json, .cursor/hooks.json, .kiro/hooks/swamp-audit.json, .opencode/plugins/swamp-audit.ts). Hooks pipe JSON to swamp audit record --from-hook --tool <tool>.
• Timeline view: swamp audit reads JSONL logs and categorizes commands as "swamp" (managed) or "direct" (unmanaged), with noise filtering, session filtering, and 7-day retention.
• Hidden for now: The audit command is hidden from --help while the feature is being tested in real repositories.

Closes #427

Test plan

• deno check — type checking passes
• deno lint — linting passes
• deno fmt — formatting passes
• deno run test — all 2576 tests pass
• deno run compile — binary compiles
• Manual testing: verified audit capture works with OpenCode in a real repository

🤖 Generated with Claude Code

Co-authored-by: Walter Heck walterheck@helixiora.com

Installation

macOS (Apple Silicon):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.232225.0-sha.16e1ce94/swamp-darwin-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

macOS (Intel):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.232225.0-sha.16e1ce94/swamp-darwin-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (x86_64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.232225.0-sha.16e1ce94/swamp-linux-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (aarch64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.232225.0-sha.16e1ce94/swamp-linux-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

What's Changed

• docs: remove CLI command sections from design documents (#570)

Summary

• Remove ## CLI Commands sections from all 7 design documents: agent, extension, inputs, models, repo, vaults, and workflow
• Fix minor markdown formatting (table alignment, trailing whitespace, italic syntax)

Why

The design documents in design/ describe domain concepts and architecture — entities, aggregates, data flows, and invariants. The ## CLI Commands sections were originally written as implementation specs when building the CLI, but they serve no ongoing purpose:

1. They drift. The CLI evolves faster than these docs get updated, so the sections become misleading rather than helpful.
2. They're redundant. Every command already has authoritative --help output and the swamp-* skills provide structured guidance for agents.
3. They blur the purpose. Design docs should describe what the domain is, not how to invoke it from a terminal. Mixing the two makes the docs harder to use as architectural references.

Files changed

Test plan

• No code changes — design docs only
• Verified no broken cross-references within the remaining content

🤖 Generated with Claude Code

Installation

macOS (Apple Silicon):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.220424.0-sha.cc1fb239/swamp-darwin-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

macOS (Intel):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.220424.0-sha.cc1fb239/swamp-darwin-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (x86_64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.220424.0-sha.cc1fb239/swamp-linux-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (aarch64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260302.220424.0-sha.cc1fb239/swamp-linux-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/