First Steps in the Swamp

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:

1. 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.
2. 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.
3. 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.
4. 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