Start a Task with swamp start

This guide shows you how to go from a freshly installed Swamp to an AI agent working on your own task with swamp start, and how to come back to that task later. swamp start runs on a desktop with a browser; for CI, containers or a repo you set up yourself, use swamp repo init instead (see Set up a repo directly).

Start

Run:

$ swamp start

swamp start opens a page on 127.0.0.1 in your browser. The terminal keeps the page running:

✓ Signed in to Swamp Club as alice

Open this page in your browser to continue:
  http://127.0.0.1:56732/dashboard/start#token=...
This terminal keeps the page running. Press Ctrl-C to stop it.

swamp start needs no credential to run. If you are not signed in, the page shows only the sign-in step, and nothing else on the page works until you sign in.

On a machine where no browser opens, such as over SSH, pass --no-browser and open the printed URL yourself.

Choose a workspace

A workspace is the Swamp repo your agent works in. On the page:

Create a workspace to get a new, empty repo under ~/.swamp/workspaces/<name> ($SWAMP_HOME/workspaces/<name> when SWAMP_HOME is set). The page suggests a name you can change.
Import an existing Swamp repo to work in it where it is. Nothing is moved or copied.
Pick a workspace you already have.

The same workspaces are managed from the terminal with swamp workspace; see Workspace Commands.

Describe the task and launch an agent

Describe the task in your own words. Swamp saves it as a brief at tasks/<date>-<slug>.md in the workspace.
Pick an agent. The page lists every agent Swamp supports and marks the ones found on your PATH; only those can be picked. It preselects the agent you picked last. You can also set the workspace up for other agents at the same time.
Confirm that you trust the workspace folder, then launch.

Swamp opens the agent in a new terminal window in the workspace, and the agent starts by reading the brief. When no terminal window can be opened, the page shows a command to copy and run yourself.

A workspace keeps every task you give it, each with its own brief, so you can add a new task to a workspace that already has one.

Come back to a task

Run swamp start again and open the workspace. Its page lists every task, newest first, with the agent and how far it got.

Launch Agent reopens the agent without sending the task again. Claude Code, Codex and OpenCode continue their most recent conversation in the workspace; other agents open a fresh session.
To open a workspace directly, skipping the picker:
```
$ swamp start --workspace my-workspace
```
A name that is not registered yet is created under ~/.swamp/workspaces/.

More than one swamp start can have the same workspace open; the page notes when another one has it open.

Check your workspaces from the terminal

swamp start status lists your workspaces, their tasks and the agents on your PATH, without opening a page or changing anything:

$ swamp start status
✓ Signed in to Swamp Club as alice

Workspaces
  infra-health  1 task
    /Users/alice/.swamp/workspaces/infra-health
    • Summarise yesterday's failed GitHub Actions runs.
      created 2026-10-13 22:21 · launched with Claude Code

Agents
  ✓ Claude Code /Users/alice/.local/bin/claude
  ✓ Codex       /opt/homebrew/bin/codex
  ✗ Cursor      not on PATH (looked for cursor-agent)
  ...

Add --workspace <name> to show one workspace. swamp start --json reports the same information as JSON and starts nothing.

Open the dashboard

Once a workspace is open, Open dashboard in the page header shows that workspace's behaviors, workflows, runs and data, with no swamp serve running. A picker in its sidebar switches between workspaces. See Local dashboard.

Stop

Press Ctrl-C in the terminal, or close the page:

Stopped. Run `swamp start` to get back to your workspaces.

Set up a repo directly

swamp repo init sets up a Swamp repo in the current folder for the agents you name, with no browser and no workspace registry. Use it for CI, containers, or an existing project you want to set up yourself; see per-agent setup. To add such a repo to swamp start later, import it.