Swamp — Claude Code Plugin

A Claude Code plugin that brings swamp skills to any project. Connects to a central swamp serve instance — no local repo needed.

Install

claude plugin marketplace add https://git.swamp-club.com/swamp-club/swamp-plugin.git
claude plugin install swamp@swamp-club

First use

/swamp:setup                              # Install the swamp binary
/swamp:central-login wss://swamp.example.com   # Authenticate with a serve instance

What this plugin provides

swamp-plugin/
├── .claude-plugin/
│   ├── plugin.json                          # Plugin metadata
│   └── marketplace.json                     # Marketplace config
├── commands/
│   ├── setup.md                             # /swamp:setup
│   ├── login.md                             # /swamp:login
│   ├── central-login.md                     # /swamp:central-login <server-url>
│   ├── init.md                              # /swamp:init
│   ├── update.md                            # /swamp:update
│   └── workflow.md                          # /swamp:workflow [description]
├── skills/
│   ├── swamp/                               # Unified swamp CLI skill
│   │   ├── SKILL.md                         # Routing table + rules
│   │   └── references/                      # Progressive disclosure guides
│   │       ├── model/guide.md
│   │       ├── workflow/guide.md
│   │       ├── data/guide.md
│   │       ├── vault/guide.md
│   │       ├── serve/guide.md
│   │       ├── repo/guide.md
│   │       ├── extension/guide.md
│   │       ├── report/guide.md
│   │       ├── troubleshooting/guide.md
│   │       └── ...                          # + deeper references per domain
│   └── swamp-getting-started/               # Onboarding walkthrough
│       ├── SKILL.md
│       └── references/tracks.md
├── scripts/
│   ├── setup-swamp.sh                       # Idempotent install script
│   └── check.sh                             # Repo consistency checks (run in CI)
└── README.md

Skills

swamp

The unified swamp CLI skill. Uses a routing table to direct queries to the right domain guide (models, workflows, data, vaults, serve, extensions, etc.). Guides are loaded on demand — only the relevant reference is pulled into context.

swamp-getting-started

Interactive onboarding walkthrough. Guides new users through creating their first model, running it, inspecting output, and choosing next steps.

Slash commands

Command	Description
/swamp:setup	Install the swamp binary
/swamp:login	Authenticate with swamp-club
/swamp:central-login <server-url>	Authenticate with a swamp serve instance
/swamp:init	Initialize a local swamp repository
/swamp:update	Update swamp binary to latest version
/swamp:workflow [description]	Create or run a workflow from natural language

How it works

The plugin connects to a central swamp serve instance. No local swamp repo is needed — all commands route through the server.

1. /swamp:setup installs the swamp binary if not already on PATH
2. /swamp:central-login wss://swamp.example.com runs OAuth device-grant authentication and writes SWAMP_SERVE_URL to .claude/settings.json
3. All subsequent swamp commands automatically route through the server

Creating custom commands

You can add your own slash commands by creating a markdown file in the commands/ directory. Each command becomes available as /swamp:<name>.

Command format

Create commands/<name>.md with YAML frontmatter and instructions:

---
name: deploy-staging
description: Deploy the current project to the staging environment.
args: "[service-name]"
---

Run the staging deployment workflow for the given service. If no service name
was provided, ask the user which service to deploy.

Run:

\`\`\`bash
swamp workflow run deploy-staging --input service=<service-name>
\`\`\`

After the workflow completes, show the user the run output.

This creates /swamp:deploy-staging [service-name].

Fields

Field	Required	Description
name	Yes	Command name — becomes /swamp:<name>
description	Yes	Short description shown in command help
args	No	Argument format hint (e.g. "<url>", "[optional]")

The body is instructions for Claude — write it as if you're telling a colleague what to do. Claude follows these instructions when the user invokes the command.

Caveats

Installer

The setup script runs curl | sh from https://swamp-club.com/install.sh. For environments that restrict this:

• Host a pinned copy of the installer internally.
• Pre-install swamp via your package manager or golden image.
• The script is idempotent — it no-ops if swamp is already on PATH.

Licensing

This plugin is licensed under Apache-2.0. See LICENSE for details.

Binary location

The installer places the binary at (in priority order):

• ~/.local/bin/swamp (if ~/.local/bin is in PATH)
• ~/bin/swamp (if ~/bin is in PATH)
• ~/.swamp/bin/swamp (fallback; symlinked to /usr/local/bin/swamp via sudo)