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

Relationships

#1952 swamp run gc undocumented in skill's data/model quick-reference tables

Opened by brucejo75 · 9/2/2026· Shipped 9/2/2026

Description

swamp run gc is a real, working command — confirmed via swamp help run gc — that garbage-collects both workflow-run history and model-method outputs, with --dry-run, --older-than <duration> (default 30d), and -y/--force flags. It's the direct complement to swamp data gc/swamp data prune for the .swamp/outputs and workflow-run side of storage.

It does not appear anywhere in the swamp skill's agent-facing documentation:

  • Not in data/guide.md's quick-reference table (which covers data gc, data prune, etc. but nothing about outputs/runs).
  • Not in model/guide.md's quick-reference table (which lists run doctor for stale-run diagnosis, but not run gc for reclaiming their storage).
  • Not in either skill's troubleshooting reference.
  • A full-directory grep -rl "run gc" ~/.claude/skills/swamp/ returns zero matches.

Steps to reproduce

  1. Notice .swamp/outputs/ has grown large (in our case, 334MB, dominated by status and record_artifact method-call output records).
  2. Follow the shipped data skill to run swamp data gc --dry-run and swamp data prune --dry-run — these only ever touch .swamp/data, never .swamp/outputs.
  3. Search the skill's reference docs (data/guide.md, data/reference.md, model/guide.md, model/reference.md, model/references/outputs.md, troubleshooting docs) and swamp help data/swamp help model output for any output-retention mechanism. Nothing surfaces.
  4. The only documented cleanup path found for outputs is swamp model delete <name>, which deletes the entire model plus its data/outputs/logs — unusable when the model itself (e.g. a long-running factory instance) needs to be kept.
  5. swamp run gc was only discovered by cross-referencing an unrelated Lab issue (#1442) that mentions it in passing while proposing a different, larger feature (a scheduled/automatic GC policy via swamp serve). The command itself is unrelated to that issue's ask — it already exists and works today.

Impact

An agent or user following the shipped skill's guidance to manage .swamp storage growth will conclude there is no way to reclaim .swamp/outputs without deleting the owning model outright. This risks:

  • Filing a duplicate/uninformed feature request for something that already ships (nearly happened in our case).
  • Falling back to manual, unsupported file deletion directly under .swamp/, which the skill explicitly and correctly warns against elsewhere ("Use swamp commands, don't bypass it").

Suggested fix

  • Add swamp run gc (with --dry-run, --older-than, --force) to data/guide.md's quick-reference table, or add a cross-reference from it, since output/run retention is the natural adjacent concern to data retention.
  • Add it to model/guide.md's quick-reference table alongside run doctor.
  • Consider a short "Run & Output Retention" subsection in one of the two guides explicitly stating the split: data gc/data prune govern the data catalog (.swamp/data); run gc governs workflow-run history and model-method outputs (.swamp/outputs).

Environment

  • swamp CLI version: 20260901.204821.0-sha.e6558412
  • Skill location: ~/.claude/skills/swamp/references/{data,model}/guide.md and adjacent reference docs
02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 1 MOREASSIGNED+ 2 MOREREVIEW+ 7 MOREPR_MERGED+ 2 MORESESSION_SUMMARIZED

Shipped

9/2/2026, 3:58:06 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
stack72 assigned stack729/2/2026, 3:05:00 PM
Editable. Press Enter to edit.

stack72 commented 9/2/2026, 3:58:14 PM

Thanks @brucejo75 for reporting this! The fix has been merged and a release is on its way. We appreciate your contribution to swamp.

Sign in to post a ripple.