The earlier piece I wrote about Claude Code's invisible sessions made the user-facing argument: keep your project state in your repo, not in the application's storage layer, because the storage layer is in active churn. This is the architectural follow-up. It's about what is changing, what each format optimises for, and what the four-formats-in-twelve-months pattern reveals about Anthropic's product strategy for the agent surface — separately from what an individual operator should do about it.
There are four storage formats in scope, all of them either currently in production for some subset of users or still readable on disk for others. They are not minor revisions of each other. Each format encodes a different answer to the question what is a Claude session, and who is it scoped to. The migrations between them are not housekeeping. They are visible product-strategy decisions, and reading them as architectural artefacts gets you a clearer picture of where Anthropic is taking the product than reading the marketing pages does.
Let me take the four in chronological order.
Format 1 — local-agent-mode-sessions/ (the legacy form)
The first format, used through 2025 and still readable on disk for users who never deleted it, lived under a directory called local-agent-mode-sessions/. The name is the load-bearing thing. It assumes the existence of an agent mode as one feature of Claude Code among others, with its own session lineage separate from whatever else the application stored.
That assumption was correct in 2025. Claude Code at the time had a meaningful distinction between chat-style interactions and agent-mode interactions — agents could call tools, navigate the filesystem, run shell commands; chat could not. The agent-mode sessions had their own storage because they were a distinct interaction model with distinct retention behaviour, and the directory name reflected that.
What's interesting is what this format does not do. It does not key by account. It does not key by organisation. It does not assume multi-tenancy. The directory is one flat namespace of agent-mode sessions on the local machine, presumed to belong to one user who is logged into one account. The schema implicitly assumes the desktop application is a personal tool with one user identity behind it. Anthropic shipped Claude Code in 2024–2025 to a much smaller, more individual customer base than they're currently aiming at, and the storage layer reflects that customer base.
The format's limits surface only when one of the implicit assumptions breaks. The moment a user runs more than one Anthropic account on the same machine, which became necessary in late August 2025 when Anthropic introduced weekly rate limits on Pro and Max plans, the flat namespace stops being adequate. The next format would have to reconcile that.
Format 2 — claude-code-sessions/<accountId>/<orgId>/ (the current desktop form)
The current desktop format renames the directory to claude-code-sessions/ and adds two levels of nesting: accountId and then orgId. The rename and the schema change happened together in early 2026; the only public trace of the rename is GitHub issue #29373, where the community located the new path constant on line 771 of the bundled .vite/build/index.js by literally diffing build artefacts. There is no announcement, no changelog entry, no migration tool. The format simply changed.
The rename from local-agent-mode-sessions/ to claude-code-sessions/ is the small thing. The most natural reading: agent mode is no longer one feature among others — it has become what the application's session storage is for. Anthropic now ships Claude Code as a coding agent, full stop; the chat-style interaction is the legacy mode, not the headline. The directory rename is doing the strategic-shift signalling work independently of whatever the marketing copy says.
The bigger thing is the <accountId>/<orgId>/ nesting. This schema is what an enterprise-multi-tenant product looks like on disk. Each account's sessions are isolated from other accounts. Each organisation under that account has its own subdirectory. The schema is the kind of thing you build when you anticipate compliance reviews of the form can you guarantee that data from Account A is never visible to a process logged in as Account B? The nesting structure is the answer.
For enterprise customers, this is the right schema. For individual power users running multiple personal accounts to work around the weekly rate limits, this is the schema that produces the invisible-sessions pathology I wrote about in the earlier piece: roughly 90% of one user's session history sitting on the same disk, in the same parent folder, in the same JSON format, unreachable from the application that wrote it because the application is currently logged into a different accountId.
The trade-off here is structural and not accidental. Anthropic has chosen the schema that protects enterprise data isolation at the cost of individual cross-account continuity. Both groups are real customers; the schema can only optimise for one of them. The community workaround (copying JSON files manually between accountId directories, or building scripts that scan all of them) exists because the user community contains the population the schema isn't optimised for.
| Format | Year | Storage unit | Optimised for | Failure mode |
|---|---|---|---|---|
local-agent-mode-sessions/ |
2025 | Per-machine flat namespace of JSON files | Single user, single account | Stops being adequate the moment a second account is added |
claude-code-sessions/<accountId>/<orgId>/ |
2026 (current desktop) | Per-account, per-org JSON files | Enterprise multi-tenant data isolation | Cross-account session invisibility for rotation users |
vm_bundles/claudevm.bundle/ |
2026 (rolling out) | VM disk-image bundle (rootfs.img + sessiondata.img + efivars.fd) | Agent isolation via virtualisation | Opaque to user-built tooling; no JSON-file workflow |
~/.claude/projects/<slug>/ |
2024–present (CLI) | Per-project JSONL transcripts | Developer / repo-centred workflow | None observed at scale |
Format 3 — vm_bundles/claudevm.bundle/ (the in-flight form)
The third format is the one currently rolling out to some macOS users on Claude Desktop 1.4758.0, documented in GitHub issue #54428. The path is ~/Library/Application Support/Claude/vm_bundles/claudevm.bundle/, and the contents are not what the previous two formats had on disk. The bundle contains:
-
rootfs.img— a disk image holding what looks like the agent's view of a root filesystem -
sessiondata.img— a disk image holding session-state data -
efivars.fd— UEFI firmware variables, the kind of file you find at the bottom of a virtual-machine boot stack
This is qualitatively different. The previous two formats stored sessions as JSON files. This format stores them inside what is, structurally, a virtual machine image. The agent is no longer interacting with a directory of plain-text history files. It is operating inside a virtualised environment whose filesystem it can read, write, and execute against, while the host filesystem is on the other side of a virtualisation boundary.
The reading of this format that fits the most public evidence is agent isolation via virtualisation. The recurring shape of the AI-agent incidents from the last twelve months — Cursor running Claude Opus 4.6 issuing a volumeDelete against a production database; Replit's coding agent destroying a SaaStr production database during a code freeze; the various "agent had access to credentials it shouldn't have" stories from the same period — has a common cure on the platform side: put the agent inside a sandbox that physically cannot reach the host filesystem or production credentials. A VM bundle with its own rootfs.img is one shape that cure takes. The agent inside it can do anything to its own root filesystem; the host's root filesystem is not visible to it.
This is a strategic move on Anthropic's part, not just a technical one. Selling agents that can't destroy your production data, by construction rather than by prompt, is the line between Claude Code is a coding tool with safety rails and Claude Code is a coding agent platform you can run against production. The second positioning is much more valuable. It is also the one that the competition (Cursor, Replit, the various Claude-wrapper shells) hasn't yet shipped, because shipping it requires the kind of platform-engineering work that VM bundles imply.
What's lost in the migration is portability of session state in any form a user-built tool can parse. The bundles are binary disk images, not user-readable in the way the JSON files were. A migration tool written against local_*.json does not work against sessiondata.img. Whatever transparency the previous two formats offered (here are my sessions, on disk, as plain JSON, that I can grep) is going away.
The exchange is data control for agent containment. From Anthropic's product position, this is the right exchange. From a user community that has spent the last year reverse-engineering session storage to build their own tooling, it is a one-way migration into an opaque container.
Format 4 — ~/.claude/projects/<slug>/ (the CLI's parallel universe)
The fourth format is the one nobody complains about, because it was designed for a different kind of user. The CLI version of Claude Code (the claude command-line tool that ships separately from the desktop app) stores sessions in ~/.claude/projects/<slug>/. The schema is project-keyed, not account-keyed.
The behavioural consequence is dramatic. Switching accounts on the CLI updates the credentials file in ~/.claude/ and nothing else. The project's session history sits at ~/.claude/projects/<repo-slug>/ and is the same set of files no matter which Anthropic account is currently authenticated. Two collaborators with two different accounts can open the same project on the same machine and see the same session history. The rotation pattern that breaks the desktop app is invisible to the CLI; the project file structure does not change just because you swapped credentials.
This schema is documented. The ~/.claude/ directory layout has its own page in Anthropic's CLI documentation. The desktop app's storage layout has no such page. The asymmetry is not accidental. The CLI is positioned as a developer tool — its users think in terms of repositories, projects, and version-controlled work. The desktop app is positioned as a user-tier surface; its users are presumed to think in terms of accounts and conversations. The two products' storage schemas reflect these assumptions, and the assumptions diverge at exactly the point where the multi-account-rotation use case lives.
The interesting question this format raises is why didn't the desktop app inherit the CLI's schema? The CLI was the first to ship; the project-keyed approach has been working without complaint since Claude Code's early days. The desktop app was built later, and its team chose to scope sessions by account instead. The choice tracks with the product positioning — desktop is for the broader audience that includes enterprise tenants, CLI is for developers — but it means the desktop app shipped with a known-better schema available in the same company's repo and didn't use it.
The fourth format is, in that sense, the part of the quartet that makes the other three legible. It shows that Anthropic can write a project-keyed session-storage schema. The choice not to do so on the desktop side is a product-positioning decision, not an engineering capability one.
What the migrations reveal about Anthropic's product strategy
Reading the four formats as a sequence, three product-strategy moves become visible.
Move one: agent mode stopped being a feature and became the product. The rename from local-agent-mode-sessions/ to claude-code-sessions/ does this in one line of bundled JavaScript. Claude Code is now an agent, full stop; the chat-style interaction model that the original directory name implied was a peer mode is now legacy. The user community that builds tooling against the storage layer should expect the sessions to behave more like agent traces (long-running, tool-call-heavy, filesystem-interacting) and less like chat histories (short, message-list-shaped) over time.
Move two: Anthropic is going after the enterprise tier. The <accountId>/<orgId>/ nesting is what enterprise multi-tenant data isolation looks like in a filesystem. The schema would be unnecessary for individual users; the only product position that requires it is one where the customer is an organisation buying seats and expecting auditable account-level data isolation. The cost of this move falls on individual power users running multi-account rotation — they get the invisible-sessions pathology — but the move itself is straightforwardly an enterprise-positioning play.
Move three: agent isolation via virtualisation is the next platform. The VM bundle format is structurally different from the previous two, and the reasons it's different are visible in the year of public AI-agent incidents the platform-engineering tier of the industry has been trying to cure. Agents that can issue arbitrary destructive shell commands against the host machine are a problem; agents that can only issue commands against a virtualised filesystem are a much smaller problem. The migration is consequential — it deprecates an entire class of user-built session tooling — but it is the response to a real category of failure that the rest of the industry has not yet solved.
These three moves are mutually consistent. They describe a product moving from individual-developer Claude Code through enterprise multi-tenant Claude Code to enterprise-grade sandboxed agent platform. Each storage-format generation is one step along that arc, and each step is visible on disk before it is visible in the marketing copy.
What this means for tooling against the storage layer
Three formats in twelve months, with a fourth in flight, signals that any tooling depending on Anthropic's session storage has a measurable shelf life. The session-storage layer is not a user-facing contract; it is an internal implementation detail Anthropic reserves the right to change. Tooling against the JSON-file format will stop working when the VM bundles ship; tooling against the VM bundle layout will stop working when whatever comes after them ships. The state that survives is what the user wrote into their own repository: handoff files, notes, project-controlled artefacts that no Anthropic migration touches.
The four-format quartet, on that reading, is not a complaint. It is a pattern. Anthropic is making fast architectural decisions about a product still finding its position, and the decisions look reasonable as product-strategy moves. The cost of the speed is borne by the user community whose tooling has to be re-derived after each migration, and the only architecturally durable response is to keep the state worth keeping outside the layer that's in active redesign. The formats are interesting to watch; almost everything they store is the kind of state you should not be relying on them to keep for you.
Top comments (0)