Skip to main content

OPERATIONAL COMMANDS

swamp run

Track and diagnose in-flight behavior method and workflow runs. The run tracker records every execution in a local SQLite database with heartbeat-based liveness detection. For conceptual background, see The Run Tracker.

swamp run history

List active and recent runs (behavior methods and workflows). Defaults to runs from the last 24 hours.

swamp run history
Flag Description
--active Show only currently running executions (mutually exclusive with --all)
--all Show all tracked runs, not just recent (mutually exclusive with --active)
--server <url> Run through a swamp serve server (ws:// or http://) instead of locally (env: SWAMP_SERVE_URL)
--token <token> Server token in <name>.<secret> format; only applies with --server (env: SWAMP_SERVER_TOKEN)
--repo-dir <dir> Repository directory (env: SWAMP_REPO_DIR)

Text output:

STATUS     KIND    NAME                   ID        AGE  PID    HOST             INITIATED BY
running    method  command/shell/execute  cc665a58  3s   18669  Mac.localdomain  user:stack72
completed  method  command/shell/execute  3760deda  25s  18783  Mac.localdomain  user:stack72
cancelled  method  command/shell/execute  cc665a58  39s  18669  Mac.localdomain  ghost

When no runs are tracked, the output is:

No tracked runs.

JSON output (--json):

{
  "runs": [
    {
      "id": "6a7290fa-5cbb-4d24-b043-1cfc6127bbce",
      "runKind": "model_method",
      "modelType": "command/shell",
      "methodName": "execute",
      "workflowName": null,
      "pid": 18920,
      "hostname": "Mac.localdomain",
      "status": "running",
      "startedAt": "2026-07-02T00:13:06.113Z",
      "heartbeatAt": "2026-07-02T00:13:06.113Z",
      "stale": false,
      "initiatedBy": "user:stack72"
    }
  ]
}

Each run object includes:

Field Type Description
id string Unique run identifier
runKind string model_method (a behavior method run) or workflow
modelType string or null Behavior type (e.g., command/shell), null for workflows
methodName string or null Method name, null for workflows
workflowName string or null Workflow name, null for behavior methods
pid number OS process ID of the executing process
hostname string Machine hostname where the run is executing
status string running, completed, failed, or cancelled
startedAt string ISO 8601 timestamp
heartbeatAt string ISO 8601 timestamp of the last heartbeat
stale boolean true if the heartbeat has expired and the process is dead
initiatedBy string or null Principal who started the run (e.g. user:stack72, ghost). Absent on runs created before this field was added

Examples:

swamp run history                        # recent runs (last 24h)
swamp run history --active               # what's running now
swamp run history --all                  # full history (7-day retention)
swamp run history --server ws://host:9090 # query a remote server

swamp run doctor

Diagnose stale or orphaned runs in the run tracker. A tracked run is stale when either:

  • its heartbeat is older than the 90-second TTL, or
  • it was started on this host and its process is no longer alive. Such a run is stale straight away, without waiting for the TTL.

A workflow run is orphaned when its run record is still running but its owning process is gone.

swamp run doctor
Flag Description
--fix Reap stale runs and settle orphaned workflow runs instead of just reporting them
--server <url> Run through a swamp serve server (ws:// or http://) instead of locally (env: SWAMP_SERVE_URL)
--token <token> Server token in <name>.<secret> format; only applies with --server (env: SWAMP_SERVER_TOKEN)
--repo-dir <dir> Repository directory (env: SWAMP_REPO_DIR)

When stale runs are detected:

2 stale run(s) detected:
KIND      NAME                   ID        HEARTBEAT AGE  PID    HOST
method    command/shell/execute  3fc80c74  13s            41285  Mac.localdomain
workflow  slow                   faebb8ba  13s            41285  Mac.localdomain

Run with --fix to automatically reap stale runs.

1 orphaned workflow run(s) whose owner is gone:
Run with --fix to automatically reap orphaned workflow runs.

With --fix, stale tracker rows are reaped and become interrupted. Each orphaned workflow run record is settled too: the run becomes interrupted with interrupt_reason: owner_process_dead, and its in-flight steps become unknown.

2 stale run(s) detected:
KIND      NAME                   ID        HEARTBEAT AGE  PID    HOST
method    command/shell/execute  519a69c9  7s             41581  Mac.localdomain
workflow  slow                   0009e429  7s             41581  Mac.localdomain

Reaped 2 stale run(s).

1 orphaned workflow run(s) whose owner is gone:
Reaped 1 orphaned workflow run(s).

JSON output (--json):

{
  "totalTracked": 2,
  "active": 0,
  "stale": 2,
  "reaped": 0,
  "orphanedWorkflowRuns": 1,
  "orphanedReaped": 0,
  "activeRuns": [],
  "staleRuns": [
    {
      "id": "faebb8ba-cb7b-43a2-90d7-d39b1dfd2db5",
      "runKind": "workflow",
      "modelType": null,
      "methodName": null,
      "workflowName": "slow",
      "pid": 41285,
      "hostname": "Mac.localdomain",
      "status": "running",
      "startedAt": "2026-10-02T01:26:08.889Z",
      "heartbeatAt": "2026-10-02T01:26:08.889Z",
      "stale": true
    }
  ]
}

orphanedWorkflowRuns counts workflow run records left running by a dead owner; orphanedReaped counts those --fix settled. --server reports the same fields.

To settle one stuck workflow run without running the doctor, use swamp workflow recover <workflow> --run <id> — see Checkpoint recovery.

When no active or stale runs exist:

No active or stale runs.

For a task-oriented walkthrough, see Clear Stuck Runs.

Examples:

swamp run doctor                           # report stale runs
swamp run doctor --fix                     # reap stale runs automatically
swamp run doctor --server ws://host:9090   # diagnose on a remote server

swamp run gc

Garbage-collect old workflow runs and behavior method outputs. Cleans .swamp/workflow-runs/ and .swamp/outputs/, which swamp data gc does not cover.

swamp run gc

Each collected run's evaluated-workflow snapshot (.swamp/workflows-evaluated/runs/<run-id>/) is deleted with it. A snapshot with no run record is swept once it is older than both the workflow-run retention and one hour, so a run that is just starting keeps its snapshot.

Running and suspended workflow runs are never deleted regardless of age. Pending and running behavior method outputs are never deleted.

When .swamp.yaml sets garbageCollection.autoDefinitions, run gc also removes idle auto-definitions older than it. An auto-definition whose last output the same run gc removes is counted as idle. The confirmation prompt and --dry-run name each auto-definition to be removed.

Repository defaults: when --older-than is not passed, run gc uses the .swamp.yaml garbageCollection keys workflowRuns, outputs and evaluatedSnapshots, each falling back to retention, and 30d when neither is set. Auto-definitions are removed only when autoDefinitions is set. With garbageCollection.automatic on, swamp runs the same collection on its own; see Configure Retention.

Flag Description
--dry-run Show what would be deleted without deleting
-y, --yes Skip confirmation prompt (--force / -f also accepted)
--older-than <duration> Retention period for runs and outputs — overrides the .swamp.yaml defaults for this invocation; never applies to autoDefinitions. Units: m=minutes, h=hours, d=days, w=weeks, mo=months, y=years (default: 30d)
--json Output in JSON format (non-interactive)
--repo-dir <dir> Repository directory (env: SWAMP_REPO_DIR)
--server Run against a remote swamp serve instance (env: SWAMP_SERVE_URL)
--token Server token in <name>.<secret> format; only with --server (overrides stored credentials and SWAMP_SERVER_TOKEN)

JSON output (--json):

{
  "workflowRunsDeleted": 0,
  "workflowRunBytesReclaimed": 0,
  "outputsDeleted": 0,
  "outputBytesReclaimed": 0,
  "evaluatedSnapshotsDeleted": 0,
  "evaluatedSnapshotBytesReclaimed": 0,
  "totalBytesReclaimed": 0,
  "autoDefinitionsDeleted": 1,
  "autoDefinitions": [{ "name": "nightly-0412", "type": "command/shell" }],
  "dryRun": true
}

Each field:

Field Type Description
workflowRunsDeleted number Number of workflow run directories removed
workflowRunBytesReclaimed number Bytes freed from workflow runs
outputsDeleted number Number of behavior method output directories removed
outputBytesReclaimed number Bytes freed from behavior method outputs
evaluatedSnapshotsDeleted number Number of per-run evaluated-workflow snapshots removed
evaluatedSnapshotBytesReclaimed number Bytes freed from those snapshots
totalBytesReclaimed number Total bytes freed (workflow runs + outputs + snapshots); excludes auto-definitions
autoDefinitionsDeleted number Number of idle auto-definitions removed
autoDefinitions array {name, type} of each auto-definition removed
dryRun boolean true when --dry-run was passed; the counts are what would be removed

Log output:

Run GC complete: deleted 3 workflow run(s) ("12.0 KB"), 5 output(s) ("1.2 MB"), 3 run snapshot(s) ("4.5 KB"), total: 11 items ("1.2 MB")

When auto-definitions are removed, a second line follows, listing up to 20 as name (type) and the rest as and N more:

Run GC removed 2 idle auto-definition(s):
  nightly-0411 (command/shell)
  nightly-0412 (command/shell)

With --dry-run the lines start Run GC dry run: would delete and Run GC dry run: would remove. Without --dry-run or --yes, a Run GC preview: line with the same counts, and a preview line and list for auto-definitions, are shown before the confirmation prompt.

Examples:

swamp run gc --dry-run                   # preview what would be collected
swamp run gc --yes                       # run with default 30-day retention
swamp run gc --older-than 7d             # delete runs older than 7 days
swamp run gc --json --older-than 14d     # non-interactive, structured output

swamp datastore lock

Inspect and force-release datastore locks. Behavior method runs acquire a per-behavior file lock to serialize concurrent access (see Per-Behavior Method Locking). These commands are the breakglass for stuck locks.

swamp datastore lock status

Show who holds the datastore lock — the behavior, PID, hostname, and acquisition time.

swamp datastore lock status
Flag Description
--repo-dir <dir> Repository directory (env: SWAMP_REPO_DIR)

Examples:

swamp datastore lock status                  # check if any lock is held

swamp datastore lock release

Force-release a stuck datastore lock. Requires --force to confirm.

swamp datastore lock release --force
Flag Description
--force Required to confirm force release
--behavior <behavior> Release a specific behavior's lock (type/name format, e.g. aws-ec2/my-server); --model is accepted as a compatibility alias
--repo-dir <dir> Repository directory (env: SWAMP_REPO_DIR)

Without --behavior, releases the global datastore lock. With --behavior, releases only the named behavior's lock.

Examples:

swamp datastore lock release --force                              # release global lock
swamp datastore lock release --force --behavior aws-ec2/my-server # release a behavior lock

swamp audit

View an audit timeline of Swamp vs direct CLI commands.

swamp audit
Flag Default Description
--repo-dir <dir> . Repository directory (env: SWAMP_REPO_DIR)
--hours <n> 24 Number of hours to look back
--all Show all commands including noise
--session <id> Filter by session ID
--include-diagnostic Include rows written by swamp doctor audit smoke test
--server Run against a remote swamp serve instance
--token Server token in <name>.<secret> format

With --server on a server with authentication, the caller needs admin on access:audit; a read grant on behaviors is not enough.

swamp audit install --user

Add Swamp's audit hook to the Claude Code user settings: settings.json in $CLAUDE_CONFIG_DIR when set, otherwise ~/.claude/settings.json. The hook records Bash and PowerShell calls whose working directory is inside any Swamp repository, wherever the session started. It runs Swamp on every such call in every project.

swamp audit install --user
Flag Description
--user Install into the Claude Code user settings. Required.

Without --user the command fails:

Error: swamp audit install needs --user: it manages the hook in your Claude Code user settings. The hook in a repo's .claude/settings.local.json is managed by `swamp repo upgrade`.

Install keeps every other key in the file. When the file already runs the hook, nothing changes. --json output:

{
  "action": "install",
  "scope": "user",
  "tool": "claude",
  "settingsPath": "/Users/you/.claude/settings.json",
  "changed": false
}

changed is false when the file already had the hook.

swamp audit uninstall --user

Remove the audit hook entries Swamp added from the Claude Code user settings. Entries that differ from the one Swamp writes are left in place.

swamp audit uninstall --user
Flag Description
--user Remove from the Claude Code user settings. Required.

--json output has the same shape as install, with "action": "uninstall".


swamp summarise

Show a high-level overview of repository activity — method executions, workflows, and data. Also available as swamp summarize.

swamp summarise
Flag Default Description
--repo-dir <dir> . Repository directory (env: SWAMP_REPO_DIR)
--since <dur> 7d Look-back window (e.g., 1h, 1d, 7d, 1w)
--limit <n> Cap per-group run details
--server Run against a remote swamp serve instance
--token Server token in <name>.<secret> format

swamp telemetry stats

View telemetry usage statistics. Reads the usage telemetry spool and does not require a repository. For what each entry contains, see Usage Telemetry Events.

swamp telemetry stats
Flag Default Description
--days <n> 2 Number of days to report

When the spool holds no entries for the window, the command prints No telemetry data found. and one explanation: an opt-out in effect, no flush recorded yet, or the outcome of the last flush. See Empty spool.


swamp source

Manage the local copy of Swamp source code used for troubleshooting.

swamp source fetch

Download Swamp source code from GitHub.

swamp source fetch
Flag Description
--version <version> Version to fetch (tag or main). Default: latest.

swamp source path

Show the Swamp source location and installed version.

swamp source path

No flags.

swamp source clean

Remove downloaded Swamp source.

swamp source clean

No flags.