Skip to main content
← Back to list
01Issue
FeatureShippedSwamp CLIPublic
Assigneesstack72

Relationships

#3692 README.md needs updating with current language and content

Opened by swamp_lord · 10/20/2026· Shipped 10/21/2026

Problem

The top-level README.md has drifted from how swamp describes itself on swamp-club.com. Examples:

  • Tagline is wrong. The README opens with "Deterministic Automation for AI Agents" (the banner alt text says "Swamp — AI Automation for Hackers"), and the intro paragraph says Swamp "supercharges AI agents to create operational workflows". swamp-club.com uses:
    • Tagline: "The right way to build with AI"
    • Subheadline: "Build AI systems from repeatable behaviors, rather than token-hungry agent-centric designs."
  • Out-of-date "model" terminology. Models are now behaviors (swamp behavior is the preferred spelling; swamp model still works as the old name). The README still talks about models throughout, for example:
    • "The agent will create models, wire up workflows, and run them"
    • The core concepts list: "Models — Typed representations of external systems…", "Definitions … instantiate a model type…", "Workflows — Orchestrate model method executions…"
    • "### User-Defined Models": "Extend Swamp with custom TypeScript models…"
    • The shell completion, data storage and telemetry sections, which refer to model names, model data and model types
  • Core concepts don't match the site. swamp-club.com describes the primitives as:
    • Behaviors — reusable, composable units that break problems into manageable, scalable components
    • Workflows — connected sequences of behaviors that run in order (e.g. fetch-alert → inspect-cluster → triage → route-to-slack)
    • Extensions — ready-made integrations connecting to APIs, databases and services
    • Vaults — secure credential storage that injects secrets only when they're needed and redacts them from output
    • Datastore — structured data storage with versioning, indexing and lifetime management
  • Missing the site's "why it's better" points: works with your favorite harness, connects to any API, stores and queries data, keeps secrets safe, and lets you "see exactly what happened every time".

Proposed solution

Rewrite the README's intro and concepts so they match swamp-club.com:

  • Replace the tagline, banner alt text and intro paragraph with the site's tagline and subheadline
  • Use behavior terminology everywhere, mentioning swamp model only as the old name that still works
  • Align the core concepts list with the site's behaviors / workflows / extensions / vaults / datastore descriptions
  • Check the remaining sections (getting started, extensions, completion, storage, telemetry) against the current CLI and update any wording that has drifted
02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 1 MOREASSIGNED+ 2 MOREREVIEW+ 7 MOREPR_MERGED+ 2 MORESESSION_SUMMARIZED

Shipped

10/21/2026, 12:59:39 AM

Click a lifecycle step above to view its details.

03Sludge Pulse
stack72 assigned stack7210/21/2026, 12:32:32 AM

Sign in to post a ripple.