Collect local Claude Code data

Runs the claude-code-local adapter over this machine's own Claude Code files. It reads only what is already on disk — nothing needs to be enabled in Claude Code, and it works on history that predates the collector.

1. Resolve the source directory

The location is not fixed. Resolve in this order and report which one won:

if   [ -n "$CLAUDE_CONFIG_DIR" ];  then SRC="$CLAUDE_CONFIG_DIR/projects"
elif [ -n "$XDG_CONFIG_HOME" ];    then SRC="$XDG_CONFIG_HOME/claude/projects"
else                                    SRC="$HOME/.claude/projects"
fi
ls -d "$SRC" && du -sh "$SRC"

asz performs the same resolution internally, so normally you do not pass source_root at all. Set it only when collecting from a copy or a mounted corpus.

2. Build

make build          # -> ./bin/asz

3. See what is discoverable before collecting

./bin/asz sources

Reports one row per session with its stream, meta, journal and manifest counts, then a footer naming any session whose files span more than one source directory. Read it for two things:

• filtered: N session(s) excluded by config — the default config excludes /private/tmp/** (Claude Code's own agent scratchpads). If a session you expect is missing, this is why.
• sessions spanning several directories — normal. A child agent that ran in a different working directory is filed under that directory instead.

4. Collect

Default storage root is ./data, relative to the working directory.

./bin/asz collect -once          # single pass; the backfill path
./bin/asz collect                # watch mode: a pass now, then every 10 minutes

To land somewhere else, write a config and pass it:

# collect.yaml
storage:
  root: /tmp/asz-data
adapters:
  - name: claude-code-local
    enabled: true
    collector:
      mode: once

./bin/asz collect -config collect.yaml

Without -config, a command run from the repository root reads the asz.yaml there. Its values are the built-in defaults: storage root ./data, watch mode, a 10 minute interval. Pass a file like the one above when you want a single backfill pass into another directory.

5. Read the result line

sessions=61 sources=5831 landed=5831 records=364051 bytes=1.0GB
gone=0 conflicts=0 busy=0 pending=0 errors=0 (2m16s)

pending or errors above zero means the pass did not collect everything, and asz collect exits non-zero. A clean pass is pending=0 errors=0.

Re-running is cheap and safe: cursors make a steady-state pass ~1s over several thousand sources, and landing is idempotent by design.

What lands where

<root>/<session-id>/
    session.state                                   next_seq, liveness, last scan
    streams/main/        transcript.cursor · transcript-<ts>-<seq>.sd
    streams/<agent-id>/  transcript.cursor · transcript-… · meta.cursor · meta-…
    runs/<run-id>/       journal.cursor · journal-… · manifest.cursor · manifest-… · script.cursor · script-…
    index/               entries.bin · index.state
<root>/_conversations/<id>/rounds/r000001-<digest>.sf   written by asz parse

Landed files are Session Data (.sd), not copies of the source lines. See docs/en/formats/storage-root.md.

Landed files are write-once and read-only. Each is a header line plus one line per source record, with the source bytes preserved verbatim in payload.

Purging a session is rm -rf <root>/<session-id>/.

If something looks wrong

• A session is missing — check the filtered line first, then asz sources.
• conflicts is non-zero — the cursor for that source is now sticky. Inspect state in its cursor file; the source was rotated, truncated, or rewritten behind the position we had already consumed.
• Nothing is discovered — confirm step 1 resolved to a directory that exists and contains per-project subdirectories.

Do not hand-edit anything under the storage root. Cursors and landed files are consistent only as written.