Skip to content

perf(storage): parallelize Claude Code transcript listing - #5096

Open
E2ern1ty wants to merge 1 commit into
apache:mainfrom
E2ern1ty:perf/claude-transcript-parallel-list
Open

perf(storage): parallelize Claude Code transcript listing#5096
E2ern1ty wants to merge 1 commit into
apache:mainfrom
E2ern1ty:perf/claude-transcript-parallel-list

Conversation

@E2ern1ty

@E2ern1ty E2ern1ty commented Sep 9, 2026

Copy link
Copy Markdown

Summary

Listing Claude Code transcripts walked the projects directory and every transcript one await at a time, so a full scan serialized its round trips through the thread pool instead of overlapping them — and as the adapter's own comments note, the catalog is listed once per search term, so the walk is paid again on files that did not change.

The directory walk, the per-file stats, and the summary derivations are now concurrent:

  • listSessions derives all summaries via Promise.all instead of one await per file. #summaryOf never throws and only touches the summary cache at distinct keys (one file per session id), so the calls are independent; results keep the original order and the final sort is stable.
  • #transcriptFiles lists project directories and stats candidate files concurrently. The newest-wins dedup stays a sequential, order-independent reduce (its tie-break names the path, not the iteration order), so completion order cannot change which file wins.
  • #parse takes the file size the cache check already stat'ed, instead of stat'ing the same file a second time.

Measured on 1000 seeded transcripts (20 projects, ~50 records each): warm relist (all files cached) drops from ~20 ms to ~5 ms; the first listing from ~155 ms to ~120 ms.

Also adds a test pinning the previously-untested dedup rule that the concurrent walk must preserve: one session id under two project directories must resolve to the newest copy in both list and read.

Verification

  • npm --workspace @maka/storage run typecheck — clean
  • npm --workspace @maka/storage run test:dist — 1215 pass / 0 fail, including the new test
  • npx biome check on both changed files — clean
  • Before/after benchmark (mean of 2 runs each, 1000 transcripts): warm listSessions 20–22 ms → 5–8 ms; cold 155–156 ms → 118–128 ms

AI use

Select exactly one:

  • No generative tool made a substantive contribution
  • Generative tooling made a substantive contribution

Tool(s) and scope: ZCode authored the change, the new test, and this description; benchmark numbers were measured locally on real runs.

Checklist

  • Tests cover the change and fail without it
  • Lint, format, typecheck and the affected suites pass locally

Note: this is a behavior-preserving performance change, so no test fails without it; the new test pins the newest-wins dedup invariant the concurrent walk must uphold.

Does this PR entail a change in behavior?

  • Yes — described under Summary above
  • No

Listing walked the projects directory and every transcript one await at
a time, so a full scan serialized its round trips through the thread
pool instead of overlapping them — and the catalog is listed once per
search term, so the walk is paid again on files that did not change.
With 1000 local transcripts the warm relist drops from ~20ms to ~5ms
here, and the first listing from ~155ms to ~120ms.

The directory walk, the per-file stats, and the summary derivations are
now concurrent. Behavior is unchanged: per-item failures are still
swallowed individually, the newest-wins dedup is order-independent (its
tie-break names the path, not the iteration order), and the final sort
is stable over the same input order. #parse also reuses the size the
cache check already stat'ed rather than stat'ing the same file twice.

Generated-by: ZCode
@github-actions github-actions Bot added the effort/M Under 500 readable lines label Sep 9, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

effort/M Under 500 readable lines

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant