First Steps in the Swamp

A new open-source framework called Swamp enables AI agents to create and execute deterministic, versioned workflows through simple command-line operations, starting with installation via curl and repository initialization. The framework automatically documents itself to AI agents like Claude Code, allowing users to create models, run them, and query execution data as a versioned database using CEL expressions. Swamp transforms ephemeral agent outputs into persistent, queryable artifacts, providing an audit trail and structured data management for AI-driven automation.

Day one I got muddy. Day two I read the map. Day three, three weeks later, is the post I would have wanted on day one: the actual commands to type, in the actual order, to go from “deterministic automation for AI agent”, whatever that means, to a working workflow with versioned data you can query. No theory this time. Well, almost. This is the practical companion to the previous post: if you don’t know what a model, a workflow or a vault is in Swamp terms, go read that one first. We’ll wait. We have time, we’re a swamp. One prerequisite before the commands: you need an AI agent. Swamp is designed to be operated by agents, not just used next to them. Claude Code is the assumed default and what I use mostly , but any decent coding agent works. The point, as we’ll see, is that you mostly don’t write Swamp YAML by hand — your agent does, and Swamp gives it the rails. Step 0 — Install curl -fsSL https://swamp-club.com/install.sh | sh Yes, the infamous curl-pipe-sh. We’ve all made our peace with it, or at least we pretend convincingly. Verify it landed: swamp version If the command is not found, restart your shell or add ~/.local/bin to your PATH. Twenty-five years of Unix and this sentence is still in every tutorial ever written. There’s something comforting in that. Step 1 — Initialize a repo Any repo. A new one, an existing project, the place where your podcast scripts live. For a first dip, make a sandbox: mkdir my-swamp-project cd my-swamp-project swamp repo init You get a glorious ASCII banner “WELCOME TO THE CLUB — for hackers, by hackers” and, more importantly, a scaffold: ls -a .claude CLAUDE.md .gitignore models .swamp .swamp.yaml vaults workflows Pay attention to two things here: .claude/ and CLAUDE.md — this is how the agent learns Swamp. The skills are auto-discovered: open Claude Code in this directory and it already knows the framework. No prompting liturgy, no copy-pasted system prompts. The framework documents itself to its own operator, which is still my favorite mildly-unsettling feature. .swamp/ — this is where every execution will leave typed, versioned, queryable data. The substrate. The thing that stops your agent’s work from dissolving into chat history like tears in rain. Step 2 — Create your first model don’t write it, ask for it Open Claude Code in the repo and ask, in plain language: Create a command/shell model called hello-world that echoes "Hello from the swamp " The agent creates a YAML definition under models/command/shell/. This is the division of labor I praised on day two, now visible on disk: logic lives in TypeScript in the model type , configuration lives in YAML in your model definition . The agent reasons over data, not over code. Old Puppet hands: yes, this smells exactly like the resource abstraction layer. I know. I checked my pulse too. Step 3 — Run it swamp model method run hello-world execute You get your Hello from the swamp , but the interesting part is what comes after: a method summary report telling you that the run produced a result resource and a log file, both saved and versioned under .swamp/data/. Every run. Automatically. An audit trail as a first-class citizen, not something you bolt on later when the auditors call. Step 4 — Query the data This is the moment it clicked for me, so don’t skip it: swamp data query 'modelName == "hello-world"' Two artifacts, versioned. Now extract just the stdout: swamp data query \ 'modelName == "hello-world" && specName == "result"' \ --select 'attributes.stdout' Hello from the swamp Those predicates are CEL expressions — the same expression language used inside model definitions and workflows to wire outputs into inputs. Learn the query syntax here, at the CLI, where mistakes are free, and you’ve learned the glue of the whole framework. Your agent’s executions are no longer ephemeral logs. They’re a queryable database. Sit with that for a second. Step 5 — Compose a workflow and extend Swamp while you’re at it Now the real demo. Back in Claude Code, ask for something Swamp can’t do yet: Create a new extension model type named @tutorial/random-status that randomly returns one of a list of statuses, storing it in a resource named "output" with a "status" property. Then create a model called weather-report that uses it to return one of: murky, misty, gloomy, stinky and humid. Then create a command/shell model called morning-message. Create a workflow called swamp-morning with two jobs: a "gather" job that runs hello-world and weather-report, and a "combine" job that depends on gather and runs morning-message, passing the hello-world stdout and the weather-report status into its command. Notice what just happened in one prompt: a new extension new capability, packaged , two new models, and a workflow — a DAG with a parallel gather job feeding a dependent combine job. Files appear under extensions/, models/ and workflows/. All reviewable, all in git, before anything runs. Run it: swamp workflow run swamp-morning Hello from the swamp The weather is gloomy - best to stay inside. The two gather steps run in parallel, combine waits for both, every edge is typed, every node leaves versioned data behind. Query the final result like before: swamp data query \ 'modelName == "morning-message" && specName == "result"' \ --select 'attributes.stdout' A pipeline where the second run is deterministic instead of a fresh improvisation. That’s the whole pitch, demonstrated in a sandbox in under half an hour. Step 6 — When things go wrong they will, it’s a swamp swamp doctor Checks installation health, broken hooks, unhealthy extensions, malformed workflows, vaults, and — bless them — cleartext secrets you left lying around. Run it early, run it often. On day one this command would have saved me several hours and an indecent amount of tokens. Where to wade next Once the hello-world ritual is done, the actual exploration starts. My suggested order: Vaults. Create one, store a secret, reference it via expression in a model. Local encrypted storage to start; AWS Secrets Manager or 1Password when a team shows up. Boring, in the best possible sense. The extensions registry at swamp-club.com/extensions. Browse what others built before reinventing it — there’s everything from AWS primitives to Firecracker microVM management for sandboxing Claude Code itself. A package manager for agent capabilities. Manual approval gates. Workflows can suspend at a manual approval step and wait for a human sign-off before touching production. The day you let an agent near real infrastructure, this is the feature that lets you sleep. Your own real use case. Take the thing you ask your agent to improvise more than once — podcast post-production, invoice archiving, key rotation, that messy directory you keep promising to fix — and reframe it as a workflow of typed models. The moment you do, it stops being a one-off and becomes an asset. And read the manual. The hands are muddier than ever. The difference is that now the mud is versioned. We’ll keep wading. Alvabot and Alessandro Franceschi