Agent Sessions
Security Notice
This extension includes AI agent skills that can modify AI assistant behavior. Review the skill files before installing.
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 dashboardAgent 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.
| Argument | Type | Description |
|---|---|---|
| since? | iso.date | Only 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? | string | Claude Code's transcript root. Defaults to CLAUDE_CONFIG_DIR/projects, else ~/.claude/projects. |
| codexDir? | string | Codex's rollout root. Defaults to CODEX_HOME/sessions, else ~/.codex/sessions. |
| worktreeGlobs? | array | Where 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? | array | Other repos whose sessions to import too, as paths (~ and paths relative to this repo work). Their records land in this repo. |
| all? | boolean | Import 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? | array | Repos to leave out, as paths or remote URLs. Excluding one clone leaves out every clone of its remote. Excluding this repo is an error. |
| Argument | Type | Description |
|---|---|---|
| root? | string | Probe this folder (or one database file) instead of the built-in roots: another agent's history kept elsewhere. ~ works. |
| replace? | boolean | Overwrite agent-sessions-probe-<agent>.md files already in the workspace. Off by default: the file there may hold your edits. |
Resources
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.
Modified 1 behaviors
Modified 1 skills
Modified 1 behaviors. Modified 1 skills
Modified 1 behaviors. Added 1 workflows. Added 1 skills. updated dependencies
Modified 1 behaviors
Added 1 behaviors. Added 1 skills
updated labels
- 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
Spawns a subprocess with Deno.Command().
- models/_lib/sessions/resolve.ts:74 — no reason given
- models/_lib/swampify/swamp_runs.ts:40 — no reason given
- models/_lib/whoami.ts:63 — no reason given
A field that looks like a secret but is not marked sensitive, so its value is not vaulted.
- models/_lib/contract/session_record.ts:152 — no reason given
- models/_lib/contract/swampify.ts:196 — no reason given