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 ghostWhen 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 serverswamp 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 serverswamp 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 gcEach 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 outputswamp 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 heldswamp 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 lockswamp 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 pathNo flags.
swamp source clean
Remove downloaded Swamp source.
swamp source cleanNo flags.