AI AGENT INTEGRATION

Swamp is operated through AI agents. Not as an optional integration or a convenience layer on top of a human-first interface, but as the primary design target. The CLI, the file formats, the data model, and the extension system were all shaped by the question: what does an AI agent need to do this well?

This page explains the design decisions behind that choice and how different AI coding tools interact with swamp.

Why agents are the primary interface

Automation frameworks traditionally give humans a GUI or a CLI and expect them to learn the system's concepts, memorize commands, and wire things together manually. Swamp inverts this. The human describes what they want. The agent figures out which model types exist, creates the right definitions, wires them together with expressions, and runs the result.

This works because of a structural property of swamp's design: model definitions and workflows are plain YAML files with typed schemas. An agent doesn't need special API access or a plugin SDK to create them. It reads a schema, reasons about what values to fill in, and writes a file. The same general capability that lets an agent write code lets it write swamp configuration.

The CLI reinforces this. Its default output is human-readable text that agents can also read and interpret directly. When structured parsing is needed — schema inspection, verifying resource state before a destructive operation — commands support a --json flag. Schema discovery is built in — swamp model type search and swamp model type describe let an agent explore what's available without documentation. Error messages include enough context for an agent to diagnose and retry.

The agent interface has three layers

An agent interacts with swamp through three complementary layers: instruction files, skills, and the CLI. Each layer serves a different purpose and operates at a different point in the agent's workflow.

Instruction files set the ground rules

When a swamp repository is initialized, it generates an instruction file tailored to the AI tool being used. For Claude Code, this is CLAUDE.md. For Codex, it's AGENTS.md. For Cursor, it's .cursor/rules/swamp.mdc. Each tool has its own convention for where project-level instructions live, and swamp writes to the right place.

The instruction file contains the rules an agent should follow when working with swamp: search for existing model types before building new ones, use CEL expressions to wire data between models, verify state before destructive operations. These rules don't teach the agent how swamp works in detail — they establish constraints and priorities that shape the agent's decisions throughout a session.

The instruction file also lists the available skills and tells the agent how to get started. For a new repository with no models, it directs the agent to run an interactive onboarding flow. For an existing repository, it points the agent toward the right skill for the task at hand.

Some tools share their instruction file with user content — the human's project-specific instructions coexist with swamp's generated rules in the same file. Swamp uses managed sections to delimit its content, so upgrades can refresh swamp's rules without overwriting anything the user has added. Other tools use dedicated instruction files that swamp owns entirely and overwrites on upgrade. The distinction follows from whether the tool's convention is a single shared file or a directory of scoped rule files.

Skills provide deep, on-demand knowledge

Skills are markdown documents that teach an agent how to work with a specific part of swamp. They are not code, not plugins, not function calls. They are structured instructions that any agent capable of reading and following directions can use.

The skill system uses progressive disclosure to manage context efficiently. Every skill has a short description that the agent always sees. This description acts as a trigger — when the user's request matches a skill's description, the agent loads the full skill body. If the skill references detailed documentation in a references/ subdirectory, the agent loads those on demand as needed.

This three-tier structure (metadata, body, references) matters because agent context windows are finite. Loading every skill's full content on every interaction would waste context on irrelevant material. Instead, the agent sees a menu of capabilities, loads what it needs, and drills deeper when the task requires it.

Skills cover the full surface area of swamp: creating and managing models, writing workflows, configuring vaults, building extensions, querying data, troubleshooting problems. Each skill encodes not just the mechanics (which commands to run, what YAML to write) but the judgment calls (when to use this approach vs. that one, what pitfalls to avoid, how to validate the result).

The CLI is designed for agents and humans alike

The CLI's default output is human-readable log text. Agents read this output directly — they don't need a special machine format to understand "model created" or to read a method's stdout. For operations where structured data matters — inspecting schemas, verifying resource IDs before deletion, programmatically processing query results — commands support a --json flag that produces machine-readable output.

Commands are designed to be composable. An agent can search for a model type, inspect its schema, create a definition, run a method, and query the output — all through sequential CLI calls where each step's output informs the next.

What makes a tool effective with swamp

Different AI coding tools have different capabilities, and these affect how well they work with swamp. The differences fall into a few categories.

File read/write and shell access

The minimum requirement is that the tool can read files, write files, and execute shell commands. Every supported tool meets this bar. An agent that can do these three things can create model definitions, run CLI commands, and inspect results.

Instruction file support

Most AI coding tools have a convention for project-level instructions — a file the agent reads at the start of every session to understand the project's rules and context. Swamp writes to the appropriate location for each tool. The richer the tool's instruction system (supporting sections, includes, or scoped rules), the more precisely swamp can configure the agent's behavior.

Skill loading

This is where tools diverge most significantly. Claude Code has native support for skills — the progressive disclosure system described above works as designed, with the agent automatically loading skills based on trigger patterns. Other tools approximate this by receiving the skill list in their instruction file and loading skill content through file reads when needed.

The practical difference is in efficiency. With native skill support, the agent loads exactly the knowledge it needs, when it needs it, with no wasted context. Without it, the agent either loads more than it needs or requires more explicit direction from the user about which skill to consult.

Tool-specific configuration

Some tools support additional configuration beyond instruction files. Cursor has hooks for audit recording. Kiro has agent configuration files that declare trusted commands and link to skill resources. Claude Code has settings files that configure permissions and hooks. Swamp generates these tool-specific files during initialization so the agent works well out of the box.

The range of supported tools

Swamp currently supports five AI coding tools: Claude Code, Codex, OpenCode, Kiro, and Cursor. It also supports a "none" mode for users who want swamp's CLI without agent integration. Each tool gets a tailored setup during repository initialization — the right instruction file, skills copied to the right directory, and any tool-specific configuration generated automatically.

The tools fall into natural groups based on their conventions. Some share an instruction file format, so swamp can give them identical content. Others have richer configuration systems — agent definition files, hook registrations, trusted command declarations — that swamp populates to give the agent a more integrated experience out of the box.

What varies across tools is the delivery mechanism, not the substance. Every tool receives the same rules, the same skill content, and the same CLI interface. The per-tool how-to guides cover the specific setup for each one.

Skills work across tools because they are plain text

A skill's portability comes from its format. Skills are markdown files with YAML frontmatter — no executable code, no tool-specific APIs, no plugin interfaces. Any agent that can read a file and follow instructions can use a swamp skill.

The progressive disclosure system adapts to each tool's capabilities. In Claude Code, skill metadata is injected into the system prompt and the agent loads skill bodies through native skill loading. In other tools, skill metadata appears in the instruction file and the agent reads skill bodies from disk when it decides they're relevant.

The content is the same either way. The swamp-model skill teaches the same concepts and the same commands regardless of whether it's loaded by Claude Code, Codex, or Cursor. The delivery mechanism varies; the knowledge does not.

The agent-shaped design

Several properties of swamp only make sense when you consider that agents are the primary user.

Model type schemas are self-describing. An agent can discover what a model type accepts and produces without reading documentation, because the schema is queryable through the CLI. This matters because agents are good at working with structured specifications and bad at inferring conventions from examples.

Definitions are YAML, not code. An agent producing a model definition is filling in a structured form, not writing a program. The type system catches mistakes at creation time rather than at runtime. This plays to an agent's strength (structured reasoning) and away from its weakness (subtle runtime bugs).

CEL expressions provide a typed, validated way to wire data between models. An agent can compose a complex data flow by writing expressions that the system validates before execution. The alternative — generating glue code to extract and pass values — would be fragile and hard to verify.

Data is immutable and versioned. An agent can reason about state by querying what exists rather than tracking what changed. Every operation produces a record of what it did, so the agent always has ground truth to work from.

These aren't agent-specific features bolted on after the fact. They are the system's core design, and they happen to also work well for humans who prefer working through a CLI. The difference is that a human might memorize commands and conventions over time, while an agent gets them through skills and schemas at the start of every session.