swamp: a CLI that stores AI agent automation as reviewable YAML in .swamp/

A CLI whose output is a repository, not a chat transcript

Swamp describes itself as deterministic automation for AI agents, and the README expands that into a CLI that lets agents create operational workflows that are reviewable, shareable and accurate. The tagline in the README is that it is built for agents and exists to serve people, and that all the data lives in the .swamp/ directory, referred to as the swamp. That directory is the whole design decision. Instead of an agent talking to a system and acting directly, it produces files, and the files are the artefact a human reads. The project is written in TypeScript and built as a single binary, with the Dockerfile copying a compiled swamp binary into a Deno base image. The repository layout is large, with packages/, src/, design/, evals/, verification/, integration/, extensions/, agent-constraints/ and scripts/ directories, so the tooling around the CLI is as substantial as the CLI itself.

The six concepts an agent actually manipulates

The Core Concepts section defines the vocabulary, and it is short enough to be worth reading in full because it is the API the agent programs against. Models are typed representations of external systems such as cloud resources, CLI tools and APIs, where each model type defines its metadata, arguments, methods and inputs. Definitions are YAML files that instantiate a model type with specific configuration, and they support CEL expressions for dynamic values and cross-model references. Workflows orchestrate model method executions across parallel jobs and steps, with dependency ordering and trigger conditions. Data is a set of versioned, immutable artefacts, being resources, logs and files produced by method runs, and it is searchable by tags. Vaults provide secure storage for secrets and credentials, referenced from definitions via CEL expressions. Tags are key-value labels on definitions, workflows and data that flow from definitions to produced data and can be overridden at runtime with a --tag flag.

Everything lands in a Git repository with symlink views

The storage model is specific enough to matter for review. Everything lives in a .swamp/ directory inside a Git repository, with human-friendly symlink views under /models/ and /workflows/. Those two things together are what make the output reviewable. The Git repository gives you history, diffs and pull requests over the automation itself, and the symlink views give you a directory of plain files to read rather than a database dump or a proprietary format. The README also frames the intent plainly: the agent will create models, wire up workflows and run them, all reviewable in .swamp/ before anything touches production. That sentence is the pitch. The data layer adds versioning and immutability on top, so a workflow run leaves a trail of artefacts rather than a transient effect, and those artefacts are searchable by the tags you set on the definitions that produced them.

Installing the CLI on each platform

Swamp runs on macOS and Linux on both x86_64 and arm64, and on Windows on x86_64. The install is a one-line script on each platform.

curl -fsSL https://swamp-club.com/install.sh | sh

On Windows the installer is a PowerShell one-liner.

irm https://swamp-club.com/install.ps1 | iex

The Windows installer places the binary in C:\Program Files\swamp and adds it to the system PATH when run as administrator, and otherwise in %LOCALAPPDATA%\swamp with the user PATH. The CLI can also update itself in place with a single command, and it ships shell completions for bash, zsh, fish and PowerShell, with the note that completions are directory-dependent because they return names from the current directory's swamp repository.

swamp update

The completion snippets for zsh with and without oh-my-zsh, and for fish, are printed by the same completions subcommand, so the setup is copy and paste rather than a plugin to install.

Sign in, pick a workspace, and let the agent work

The first command is swamp start, which opens your browser. The README describes the flow: you sign in to Swamp Club, which creates your swamp-club.com account if you do not have one, because swamp needs an account to run, you pick a workspace, you describe what you want automated, and you choose an AI agent found on your machine. Swamp then opens that agent in a new terminal window already working on the task, and Ctrl-C in the terminal stops the run. New workspaces are created under ~/.swamp/workspaces/, or under $SWAMP_HOME/workspaces/ when that variable is set, and you can import an existing swamp repository where it already lives. A workspace keeps every task you give it, each with its own brief in a tasks/ directory, listed newest first with a creation time, and returning to a workspace lets you reopen a task, relaunch its agent, open a different agent, or start a new one. The workspace subcommand manages all of this from the terminal with create, import, list, get and remove, where removing a workspace takes it off the list but keeps its folder.

swamp start

Initialising a repo for the four supported coding tools

To use swamp inside a project that already exists, you sign in, initialise the project as a repository, and start your agent there. The init command takes a tool flag, and the four supported tools each get their own skills directory and instruction file.

swamp auth login                   # skip if swamp start already signed you in
swamp repo init                    # Claude Code (default)
swamp repo init --tool cursor      # Cursor
swamp repo init --tool opencode    # OpenCode
swamp repo init --tool codex       # Codex

Claude Code is the default and uses .claude/skills/ with a CLAUDE.md instruction file, Cursor uses .cursor/skills/ with a .cursor/rules/swamp.mdc file, and both OpenCode and Codex use .agents/skills/ with an AGENTS.md file. The skills are bundled into the swamp binary and written into the right directory so the agent discovers them automatically, and each one teaches the agent how to search for models, create definitions, run workflows and manage vaults. You can switch tools later or run several side by side, because each tool's skills directory is independent and gitignored, with an upgrade command taking the same tool flag.

swamp repo upgrade --tool cursor

There is also a path for extending swamp itself, with custom TypeScript models placed in extensions/models/, or configured through SWAMP_MODELS_DIR or a .swamp.yaml file.

Local execution, licences, and where the limits are

Swamp states that it runs entirely on your machine and picks up environment variables from the shell you run it in, your AWS credentials, SSH keys, kubeconfig, whatever the task needs, and that no credentials leave your laptop unless a model explicitly calls an external API. That is a meaningful design commitment for agent tooling, and it also has an obvious edge: a model that reaches an external API does send data out. The licensing is more complicated than the repository field suggests. The project is marked as using a custom licence that GitHub cannot classify, and the top level of the repository carries LICENSE, COPYING, COPYING-EXCEPTION, COPYRIGHT, FILE-LICENSE-TEMPLATE.md, OSS-FAQ.md and TRADEMARKS.md, while the container image label declares AGPL-3.0-only. Read those files before shipping swamp in a product. The other practical limits are the account requirement, which the README flags with a dedicated reference page for CI and daemon use, and the fact that the agent needs to be installed on your machine already, since swamp finds it on your PATH. For teams that want the reviewable plan but not a vendor account, a plain Git repository of YAML models and workflows with a scheduler of your own is the honest alternative, at the cost of losing the agent that writes the definitions for you.

Editorial conclusion

Adopt swamp if you want agent-driven automation whose output a human can read and approve before it runs, and if you are willing to hold a swamp-club.com account and accept the licensing terms in the LICENSE and COPYING files. Do not adopt it if you need a self contained tool with no account requirement, since the README states swamp needs an account to run, and check the CI guidance for daemons before you automate around it. Verify first which of the four supported coding tools you use, since the skills and instruction files are written per tool and are switched with a flag.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. swamp-club/swamp on GitHub