Skip to main content

Agent Sessions

@swamp/agent-sessionsv2026.11.16.1· AGPL-3.0-or-later· 5d agoBEHAVIORSWORKFLOWSSKILLSACCEPTED WARNINGS
01README

Import what coding agents did in this repo as agent session records, the data the dashboard's Agent sessions page reads. The import method reads Claude Code's own transcripts and Codex's rollouts on this machine, so no hooks or setup are needed, and writes one record per session and per subagent: its turns, tool calls, times and tokens. Records stay in this repo's swamp data; nothing is sent anywhere.

Preview: the records and the page may change between versions.

Session records never store prompts, replies, reasoning, tool output or file contents. A call keeps only its target (a command line, a path, a skill name or a URL), redacted: paths become relative, home becomes ~, known secret shapes, bearer tokens and emails are masked, heredoc bodies are dropped, quoted free text (commit messages, PR bodies, inline scripts, what echo writes) keeps only its length, and text is capped at 1000 characters.

Every call is labelled swamp, bypass or neutral with a category and the rule that decided it, by rules alone. Running a program an installed extension covers (git with @swamp/git) is a bypass. Each record also carries findings that say what to tune: hand-edit loops on a definition, failure streaks, covered CLIs run directly, and reads of pulled extension source.

The assess method is different: it reads transcript text (prompts, replies and tool calls) to find the repeated chores worth automating, and writes one Swampify candidate set holding counts, per-occurrence costs and up to 5 short, redacted excerpts per candidate, plus each occurrence's time, session id and cost for compare (numbers only). No model is called; its only network call fetches the registry's public extension list, without credentials. Where the set then goes (kept local, a datastore, swamp serve) is your choice, as for any repo data.

The probe method is for agents the extension does not read yet (pi, Amp, Windsurf, Devin): it describes where and how an agent keeps its history, never what it says, and writes agent-sessions-probe-<agent>.md in the workspace for you to review with the agent-sessions skill and share privately with the swamp team, so support can be added. It reads only, calls no model and sends nothing anywhere.

The bundled swampify skill turns that set into one automated chore: ask your agent "what should I automate?". It runs import and assess, has a cheaper model you pick (Claude Code or Codex, through @swamp/agent-runner and your own login) read up to 3 example sessions for each of the top 10 candidates, and offers three to five. The readers are read-only (a claude reader is limited to Read, Grep and Glob; a codex reader to codex's read-only sandbox), leave no session file behind and return short verdicts in their own words, never transcript text. The offer, pick and built methods record the offer, your pick and what it became once getting-started has built and run it. compare then measures it from records alone, without a model: the build cost, fixing sessions included, the chore's past cost as ranges (its own calls up to whole turns), the first and latest swamp runs with their model steps' tokens, and the break-even. The skill also starts from swamp start's Swampify kick-off, then sends you to the Swampify page to review and pick; each build the page hands back runs in its own agent session, and the skill sends you back to the page for the next pick. After each build it asks whether to wire it into your agents: the targets become inputs, one run from your own repo uses --repo-dir, and a short rule for your CLAUDE.md or AGENTS.md is offered, written only on a yes.

Getting started

The bundled agent-sessions skill walks an agent through the first import: ask it to "import my agent sessions". By hand:

swamp extension pull @swamp/agent-sessions
swamp behavior create @swamp/agent-sessions sessions
swamp behavior run sessions import
swamp dashboard

Agent sessions appears in the dashboard's sidebar once the repo has session records you can read.

Methods

Method What it does
offer Record the Swampify offer from the latest candidate set: one to five options your agent wrote, and the candidates it set aside with a reason.
pick Record which option you picked, or that you declined.
built Record the behavior or workflow the pick became.
compare Write the comparison for a built option: build cost across fixing sessions, history ranges, the first and latest swamp runs with their model tokens, occurrences by hand and through swamp since, and break-even. Reads records only.
probe Describe another agent's history (pi, Amp, Windsurf, Devin, or any folder) without its content: layout, formats, key paths, value shapes and redacted samples cut to 60 characters, in a Markdown file to review and share privately. Reads only.
assess Mine Claude Code transcripts and Codex rollouts (default: all history on disk) into one ranked swampify-candidates item: repeated prompts, headless jobs, call sequences and covered CLIs, each with counts, costs and redacted excerpts. Same scope inputs as import; with all, sessions in folders that are not repos count too.
import Import this repo's Claude Code and Codex sessions, its worktrees' and every subagent's; other repos' too with repos, or every repo on the machine with all, which puts every project's commands and paths in this repo's data. Unchanged transcripts are skipped. Optional since, projectsDir, codexDir, worktreeGlobs, repos, all and exclude.

More imports

swamp behavior run sessions import --input since=2026-10-01
swamp behavior run sessions import --input 'repos:json=["~/src/api"]'
swamp behavior run sessions import --input all=true \
  --input 'exclude:json=["~/src/client-repo"]'

Run the import and the assessment on the machine that holds the transcripts. A serve worker (--remote-only) has none, and they fail saying so.

02Behaviors1
@swamp/agent-sessionsv2026.11.14.3agent_sessions.ts
fn import(since?: iso.date, projectsDir?: string, codexDir?: string, worktreeGlobs?: array, repos?: array, all?: boolean, exclude?: array)
Import this repo's Claude Code and Codex sessions, its worktrees' and their subagents' as agent session records, and those of other repos named in repos, or every repo with all. Must run on the machine that holds the transcripts.
ArgumentTypeDescription
since?iso.dateOnly import sessions whose transcript, rollout or any subagent's changed on or after this date: YYYY-MM-DD (local midnight) or an ISO 8601 time. A session started earlier but active since is imported.
projectsDir?stringClaude Code's transcript root. Defaults to CLAUDE_CONFIG_DIR/projects, else ~/.claude/projects.
codexDir?stringCodex's rollout root. Defaults to CODEX_HOME/sessions, else ~/.codex/sessions.
worktreeGlobs?arrayWhere your worktrees live, so a session whose worktree was removed can still be placed: globs such as ~/worktrees/*/<repo>, where <repo> is a repo's directory name. A match counts only when the session ran on one of that repo's branches. Empty by default: a removed worktree's sessions are skipped.
repos?arrayOther repos whose sessions to import too, as paths (~ and paths relative to this repo work). Their records land in this repo.
all?booleanImport every session on this machine whose repo can be found, not just this repo's. Every project's commands and paths, personal and client repos included, land in this repo's data, readable by anyone who can read it. Use exclude for repos that must stay out.
exclude?arrayRepos to leave out, as paths or remote URLs. Excluding one clone leaves out every clone of its remote. Excluding this repo is an error.
fn assess()
Read Claude Code transcripts and Codex rollouts in a window (default: all history on disk) and scope, prompts and replies included, and write one swampify-candidates item: the repeated chores worth automating, ranked, with counts, per-occurrence costs and short redacted excerpts. No model is called; the only network call fetches the registry's public extension list. Must run on the machine that holds the transcripts.
fn probe(root?: string, replace?: boolean)
Describe another coding agent's history (pi, Amp, Windsurf, Devin, or any folder named with root) without its content, so the swamp team can add support: for each root found, write an agent-sessions-probe-<agent> item and agent-sessions-probe-<agent>.md in the workspace root with the layout, formats, key paths, value shapes, versions and redacted samples cut to 60 characters. Reads only; calls no model and sends nothing anywhere. Must run on the machine that holds the history.
ArgumentTypeDescription
root?stringProbe this folder (or one database file) instead of the built-in roots: another agent's history kept elsewhere. ~ works.
replace?booleanOverwrite agent-sessions-probe-<agent>.md files already in the workspace. Off by default: the file there may hold your edits.
fn offer()
Write the Swampify offer from the latest candidate set on this behavior: one to five options the user's agent made of the candidates it read, and those it set aside. Refuses candidate ids the set does not hold.
fn pick()
Record which option of the Swampify offer the user picked, or decline=true when they picked none.
fn built()
Record the behavior or workflow the picked option became, once it has been built and run.
fn compare()
Measure a built Swampify option, raw against swamp, and write swampify-comparison-<option id>: the build cost (the build session and later sessions that fixed the target), past occurrences as ranges, the first swamp run and the latest successful one with their agent-runner steps' model tokens, occurrences by hand and through swamp since the build, and the break-even. Reads records only. Run import and assess first so the figures are current; must run where swamp's run records are.

Resources

session(infinite)— One coding-agent session or subagent: its turns and tool calls, never its prompts or replies (agent session record v2)
swampifyCandidates(infinite)— The repeated chores worth automating, ranked, with counts, per-occurrence costs and short redacted excerpts (Swampify candidate set v2)
swampifyOffer(infinite)— What the user's agent offered from the candidate set: one to five options in its own words, the candidates it set aside and why, and the user's pick and what it became (Swampify offer v1)
swampifyComparison(infinite)— One built Swampify option measured: the build cost, what the chore cost raw before (the chore's own calls up to whole turns), the first swamp run, occurrences by hand and through swamp since, and the break-even (Swampify comparison v2)
swampifyOccurrences(infinite)— Each occurrence of the candidates assess found, and of the offer's options' candidates: when, which session, its turns, and the chore's and the whole turns' cost. Numbers and ids only, for compare
probe(infinite)— What probe found under one root of another agent's history: layout, formats, key paths, value shapes, versions and redacted samples cut to 60 characters (agent-sessions probe v1)
registryIndex(infinite)— The registry's public extension names, cached for a day, for matching covered CLIs
importIndex(infinite)— Size and mtime of each imported transcript, so unchanged sessions are skipped
03Workflows1
@swamp/agent-sessions/swampify-understanda7ae967d-fb95-4497-956f-dfeb42b292dd

Read a few example sessions of each top Swampify candidate on a cheaper model through @swamp/agent-runner, one reader per candidate, each returning a short structured verdict and never transcript text.

readRead each candidate's example sessions, one reader after another
1.verdict${{ inputs.reader }}.run
04Skills2
agent-sessions2 files
swampify7 files
05Previous Versions14
2026.11.15.1AGPL-3.0-or-later
2026.11.14.3AGPL-3.0-or-later
2026.11.14.2AGPL-3.0-or-later

Modified 1 behaviors

2026.11.14.1AGPL-3.0-or-later
2026.11.13.2AGPL-3.0-or-later

Modified 1 skills

2026.11.13.1AGPL-3.0-or-later

Modified 1 behaviors. Modified 1 skills

2026.11.11.1AGPL-3.0-or-later

Modified 1 behaviors. Added 1 workflows. Added 1 skills. updated dependencies

2026.11.10.1AGPL-3.0-or-later

Modified 1 behaviors

2026.11.03.1AGPL-3.0-or-later

Added 1 behaviors. Added 1 skills

2026.11.02.2AGPL-3.0-or-later
2026.11.02.1AGPL-3.0-or-later

updated labels

2026.10.31.2AGPL-3.0-or-later
2026.10.31.1AGPL-3.0-or-later
2026.10.30.1AGPL-3.0-or-later
06Stats
A
100 / 100
Downloads
120
Archive size
277.3 KB
Verified by Swamp
  • Has README or module doc2/2earned
  • README has a code example1/1earned
  • README is substantive1/1earned
  • Most symbols documented1/1earned
  • No slow types (deprecated)1/1earned
  • Dependencies pass trust audit2/2earned
  • Docs keep secrets in a vault1/1earned
  • Has description1/1earned
  • Platform support declared (or universal)2/2earned
  • License2/2earned
  • Verified public repository2/2earned

08Platforms
09Labels