| name | loopbase |
| description | Discover, read, and hand off work across local AI agent sessions (Claude Code, Codex, pi — same machine). Use when you need to know what other agents/sessions have done in this project, pick up another session's work, or record what you just did so the next agent can continue. Triggers: "what else was done here", "what did the other session do", "hand off", "where did we leave off", "log this", cross-session/cross-agent context.
|
loopbase — cross-session agent memory
loopbase reads every local agent session's transcript (Claude/Codex/pi) and lets you
leave a running worklog. Output is JSON by default (pass --text for humans).
It indexes lazily on each call — no daemon, nothing to start.
The commands
loopbase list # sessions in THIS project, each with its worklog (a TOC)
loopbase search "<text>" # find sessions/turns by content (across agents) → a `turn` handle
loopbase show <session_id> # read/understand one session (map by default, then drill)
loopbase log "<what I did>" # append a worklog entry to YOUR current session
loopbase cost # token + USD spend per session (memoized at index)
loopbase insights # automation CANDIDATES: repeated/expensive tool patterns, sequences, errors
Workflows
1. "What else has happened in this project?"
loopbase list # current project (cwd → git root), most-recent first
loopbase list --all # every project
loopbase list --since 24h --agent codex
loopbase list --logs # flat worklog feed (LOG.md-style) across sessions, newest first
loopbase list --logs --all --since 7d # everything logged anywhere this week → then dive: `loopbase show <session> --log <id>`
Each session shows: id, agent, branch, title, updated, msgs,
subagents count, and nested worklog entries. The id is the handle for show.
1b. "Where did anyone look into X?" (search by content)
loopbase search "JWT refresh" # this project, across agents; each hit carries a `turn` handle
loopbase search "Necmttn/ax" --all # every project — find any session that discussed it
loopbase search "<pattern>" --regex --since 7d --agent codex
loopbase search "foo" --files # grep -l style: matching sessions + raw paths, for your own piping
A match gives { session, turn|subagent, snippet, path } — dive with the same
ladder: loopbase show <session> --turn <n> (or --agent <id> for a subagent hit).
Search is the content-addressed entry; the map is the structural one.
2. "Pick up another session's work" (the handover)
loopbase show <id> defaults to the map — never the raw transcript.
Read the map to understand; open only what you need:
loopbase show 9a6282d1 # THE MAP: worklog groups (or a flat turn outline) + unlogged tail.
# each turn has a `turn` handle + `then:{replies,tool_calls}` heatmap. No bodies.
loopbase show 9a6282d1 --turn 39 # open ONE user turn (the `turn` handle) → its messages
loopbase show 9a6282d1 --log lg_4f2a # open one worklog span's messages
loopbase show 9a6282d1 --role all # the FULL transcript (paged); --role assistant = assistant only
loopbase show 9a6282d1 --tool tu_9c # full untruncated result of ONE tool call
loopbase show 9a6282d1 --agent adaf5e2 # descend into a subagent's transcript
loopbase show 9a6282d1 --turn 39 --expand-tools # inline tool I/O within a turn
Branch on which key is present: worklog/turns = the map, messages = a
transcript view, tool = one tool result. Paged views carry a compact
more:{shown,total,next_offset} when there's more. --max-chars bounds text;
--deliver file:PATH writes to a file.
Long sessions (the map is the answer)
You never dump a long transcript. show defaults to the bounded map, and every
messages view is paged (--limit/--offset, with a shown field + hint):
loopbase show <id> — the map. If logged, worklog entries are the curated
sections; else it's the turn outline. then counts show which turns are heavy
before you open them; unlogged = work not yet worklogged.loopbase show <id> --turn <n> — open just that turn (bounded/paged).--role all only when you truly need the whole transcript (still paged).
3. "Record what I just did"
loopbase log "finished auth refactor: moved sessions to JWT" --tags infra,product \
--body "dropped the sessions table; verify is now stateless; 12 tests pass"
text = a one-line title; --tags a,b = tags; --body = optional 1–2 line
detail (outcome first). (Like a LOG.md entry: title · #tags · What.)- Session id is auto-resolved from the environment — pass nothing.
- A
log auto-spans the messages since your last log — so the worklog
becomes a table-of-contents of the session (shown in loopbase list / loopbase show,
replayable with loopbase show --log <id>). --dry-run previews the span.
Log ONE entry per batch of work, right after you finish it. Don't fire
several logs back-to-back to "catch up" — a normal log only covers what
happened since the previous one, so a second immediate log covers nothing and is
rejected ("no new messages since your last log"). So: do a batch → log it →
do the next → log it. One good line beats five empty ones.
Advanced: retro-tag a past turn range (--turns)
To backfill the worklog after the fact — label specific earlier turns rather
than auto-spanning forward — inspect first, then tag:
loopbase show <id> # read the map, note the turn range you mean
loopbase log "investigated the ax repo" --turns 6-14 --tags research
loopbase log "fixed the redirect" --turns 20 # a single turn
This is reliable only because you read the turn numbers from show first —
don't guess turn numbers from memory. A --turns entry is anchored to that exact
range and does not move the forward cursor (so normal log keeps working).
Out-of-range turns are rejected with the valid count. Use it to retro-generate a
worklog for an un-logged session, or to tag a sub-range more precisely.
4. "What repetitive work is worth automating?"
loopbase insights # this project: ranked automation candidates
loopbase insights --all --since 14d # across every project, recent window
loopbase insights --analyzer tool-ngram # just the recurring call SEQUENCES
loopbase insights --include-edits # also count Read/Edit/Write (off by default)
loopbase insights --show-signature # debug: see how raw calls collapse into buckets
Three analyzers over the stored tool-call facts: tool-freq (repeated/expensive
single calls), tool-ngram (recurring multi-call sequences), tool-errors
(tools that keep failing). Each row is ranked by real attributed USD (the
issuing message's memoized cost, joined on message id), tagged with its
dominant repo, nested with its top sub-clusters (so composio run shows
┗ INTERCOM_SEARCH ×165 · GET_CONVERSATION ×46 — a tool tally becomes a task),
and carries up to 3 session#turn examples you open with show --turn. So a row
reads like 226× · $97.57 · 23 sess · mcp__posthog__exec — spend you can
prioritize against. By default the automation lens excludes file-mutation
tools (Read/Edit/Write — the substance of coding, not scriptable; Grep/Glob
stay). These are candidates — the framework finds repeated and expensive;
whether something is deterministic enough to script is your call.
Tips
- IDs shown are short prefixes;
show accepts any unambiguous prefix.
- Errors are structured (
{error, ...}) with a stable exit-code taxonomy
(2 usage · 3 not-found · 4 invalid-value · 5 empty · 6 io).
- Log at task boundaries (after shipping a fix, finishing an investigation), not
every message — that keeps the worklog a useful map.
