Supported read access to historical session data for third-party tools

[LarsArtmann]

What I'm asking about

A supported, documented way for third-party tools to read historical
session data (workspaces, sessions, messages, todos, cost stats). Mainly
three questions at the bottom — the server API looks like it already covers
most of this, so this is partly "please consider analytics consumers in the
upcoming docs/release" and partly "what should on-disk readers do meanwhile".

Context: the read-only consumer ecosystem

There is a real ecosystem of open-source tools that read Crush's local
data — Go, Rust, TypeScript; all currently built on the
undocumented on-disk format (the Go six reviewed source-level on
2026-09-07, see
the review):

Tool	Lang	What it does with the data
junhoyeo/tokscale	Rust	token-usage tracking from per-project crush.db
jhlee0409/claude-code-history-viewer	Rust/Tauri	GUI history browser across <project>/.crush/crush.db
yigitkonur/cli-continues	TS	session handoff parser; maintains its own reverse-engineered docs of the format
Dicklesworthstone/coding_agent_session_search (CASS)	Rust	cross-agent session search over crush.db
janekbaraniewski/openusage	Go	usage tracking from .crush/crush.db per project
Pilan-AI/mnemo	Go	indexes Crush sessions into its SQLite
superbasedapp/observer	Go	agent observer via a crush adapter (deepest parser in the ecosystem)
taigrr/crunch	Go	LLM-generated daily summaries from crush.db scans
soyomarvaldezg/crush-tmux	Go	tmux status via read-only crush.db probing (#3531)
LarsArtmann/go-crush-data	Go	typed read-only library over projects.json + crush.db (mine; verified against v0.92.0 / 559ec80), plus crush-daily (private, mine) building daily per-project summaries on it

Adjacent: perplexityai/numbat
integrates via the hooks surface. vshulcz/deja-vu
merged a Crush parser (#2949 →
PR #3158, 2026-09-07)
shortly after this inventory was compiled — another JSON-parts reader
(7th Go reader).

When even motivated third parties get misled — deja-vu's Crush parser
notes: "It keeps sessions in SQLite, not in the JSON state file the
README talks about" — that's a docs gap, not a tooling gap.

What these tools all currently reverse-engineer (no upstream docs):

• <global>/projects.json registry shape and location resolution
• crush.db: sessions / messages / read_files tables (goose
  migrations evolve these — fine, but changes are invisible to readers)
• the message parts envelope ([{"type":…, "data":{…}}], 8 discriminators)
• agent child session IDs (messageID$$toolCallID)
• unix-second timestamps (the migration comments say milliseconds — they
  are not; comment fix pending in docs(db): fix timestamp unit comments in initial migration #3576). The comment has real victims:
  2 of the 6 Go readers shipped date bugs from converting with
  time.UnixMilli — their sessions landed in January 1970. Both are now
  fixed: openusage#357,
  mnemo#22 — the fixes took
  one line each; the diagnosis took reverse-engineering

This works, but breaks silently on migrations. For example, #3580
(compressing message parts) would break every JSON-parsing reader. As #2707's
author put it: "Schema isn't a public API, breaks on migrations." We know —
that's exactly why we're asking.

What I found in the repo (v0.92.0)

The server API already looks like the answer for most of this.
internal/swagger/swagger.json includes:

• GET /workspaces — would replace projects.json discovery
• GET /workspaces/{id}/sessions + /sessions/{sid} — proto.Session
  even carries parent_session_id (agent subtrees), todos, cost,
  token counts, timestamps
• GET /workspaces/{id}/sessions/{sid}/messages (+ /history)

and per @meowgorithm in #3531: "Server-client is still not officially
released, but usable and hopefully not too far off. Part of that work will
definitely be docs."

Questions

1. Enumerating historical projects. Backend.ListWorkspaces returns
   the running server's in-memory workspaces (populated via
   CreateWorkspace; I couldn't find hydration from the projects.json
   registry at startup). For analytics tools the make-or-break operation is
   "enumerate every project I have ever used, offline ones included, and
   read its full history." Could GET /workspaces (or a sibling endpoint)
   cover the registry, or is that intentionally out of scope?
2. Stability expectations for the HTTP API. Once documented, do you
   intend to treat it as a compatibility surface (semver-ish pinning), or
   best-effort/may-change for a while? Even a rough answer lets downstream
   tools decide how much to lean on it versus the DB.
3. On-disk readers meanwhile. Would you be open to blessing the goose
   migrations under internal/db/migrations as the de-facto changelog for
   read-only consumers ("watch this dir"), or a short docs note stating the
   on-disk format is unsupported and will keep changing? Either is cheap
   and removes the guesswork.

An offer, in case it's useful

If Crush ever wants an official read surface — an SDK, a docs page, or
an in-process package — I'd be glad to contribute the basis:
go-crush-data is MIT,
resolves the projects.json registry, opens every crush.db read-only,
probes schema capabilities so migrations degrade gracefully instead of
breaking, and decodes the parts envelope and todos shape, tested against
v0.92.0 plus a census of 287 real databases (71,747 todo items). It
would of course need to become a module Crush controls; the logic and
census-verified fixtures are simply there if useful. No strings
attached either way — the questions above matter more than the offer.

Happy to share what we learned from real-world data (e.g. that todos
census) if that's useful for the docs work.

Related

• Feature request: expose agent lifecycle events / observability surface for external tools #3531 — live observability surface (complementary; this post is about
  historical reads)
• Feature request: headless server mode with API #1765 — server mode (completed)
• Lifecycle hooks for external observers #2707 — lifecycle hooks (shipped)
• Feature request: built-in chat export / persistence (Markdown / JSON) #1965 — built-in export (adjacent, user-facing)

[ArcticFox2029]

Three things from the other side of this — I maintain a tool that writes agent state to disk rather than reading Crush's, so I've paid the opposite set of costs.

• An undocumented on-disk format is a contract whether anyone signed it or not. Six independent readers already exist. Whatever the next release does to that schema, it breaks them, and they'll be blamed for it. Documenting it doesn't add an obligation — it just names one that already exists.
• A read API and a stable on-disk format solve different problems. The API needs Crush running; a lot of the consumer ecosystem here is analytics and post-hoc tooling that wants to read a machine that finished working yesterday. If only one gets committed to, the file format is the one that keeps working when the process is gone.
• The cheapest useful commitment is a version field, not a schema. One integer in the file that changes when the shape does. It costs nothing to write, it turns a silent breakage into a loud one, and it doesn't oblige anyone to keep the current layout forever.

For what it's worth, the tool I work on went the other way and stores everything as plain markdown committed into the repository — no database, no format to reverse-engineer, readable in a diff. That has its own bill: it's slower, it's in code review whether you wanted it there or not, and it can't answer aggregate questions the way a SQLite file can. Not a recommendation, just the trade sitting on the other end of this one.