Use case · macOS ↔ Windows
Move Claude Code and Codex Sessions Between macOS and Windows
Reinstate is designed to move supported same-vendor Claude Code and Codex sessions between macOS and Windows even when the same project has different absolute paths. A canonical project ID links the two checkouts; agent-specific adapters reconstruct the destination’s native structural paths.
- Last verified
- Current release
- v0.6.0-rc.6
- Release status
- v0.6.0-rc.6 candidate · stable remains v0.5.1 · v0.6.0-rc.5 tagged Windows run (plus two same-artifact rechecks) ended FAIL (211/4/0/0 of 215), zero product defects, grok:E1-E3 live-backend-connectivity plus a grok version drift to 1.0.13 and an H7 digest-equality-unmeasurable gap the four PARTIAL rows · this candidate widens the verified Grok Build range to 1.0.13 and refines the H7 live-home check to per-file listing with attribution · native Windows tagged-artifact acceptance pending, macOS deferred
- Owner
- Harjot Singh Rana
Why copying the agent folder is not enough
Agent session formats contain absolute paths. A checkout at C:\src\app on Windows may be /Users/you/Code/app on macOS. Claude Code also derives a project-directory key from that path, while Codex records its structural working directory inside each rollout. A blind folder copy cannot safely reconcile those identities.
The canonical project mapping
| Identity | Windows device | macOS device |
|---|---|---|
| Canonical project ID | github.com/acme/app | github.com/acme/app |
| Local root | C:\src\app | /Users/you/Code/app |
| Portable identity | $${REPO:github.com/acme/app} | $${REPO:github.com/acme/app} |
Reinstate normalizes known structural paths during export and expands them through the destination mapping during restore. It does not search-and-replace every path-shaped string inside prompts or responses.
How the two current adapters differ
Claude Code
The destination root is used to recompute Claude's exact project-directory key. Reinstate verifies the restored session at that planned location rather than accepting the same ID elsewhere.
Claude Code details →Codex CLI
The source session_meta.cwd resolves to a project ID. Restore expands it to the destination root while retaining Codex's native date-partitioned rollout layout.
Platform status
Stable v0.2.0, v0.3.0, v0.4.0, and v0.5.1 have all passed dual-platform tagged-artifact acceptance on Apple Silicon macOS and native Windows x64. Intel macOS and WSL2 remain optional, unsupported/unverified evidence and do not block stable. The v0.6.0-rc.6 release candidate's acceptance is native Windows x64 only under the Windows-first waiver; Apple Silicon macOS is deferred until that hardware returns and is not claimed for this candidate.
Do not merge native Windows and WSL into one device.
WSL2 is a separately configured Reinstate environment with Linux path semantics. WSL1 is unsupported, and one shared agent-state folder between Windows and WSL is explicitly outside the supported model.
Cross-platform setup checklist
- Use the same pinned Reinstate version on both systems.
- Install a tested version of the same agent vendor on both systems.
- Clone the repository normally with Git on each system.
- Map the same canonical project ID to each native checkout path.
- Use one approved S3-compatible profile and the same encryption passphrase.
- Run setup checks and a pull dry-run before the first real restore.
- Close active agent processes before mutating their local session files.
What path remapping does not solve
- Different Git branches, commits, or uncommitted working-tree changes.
- Missing runtimes, tools, MCP servers, skills, hooks, or plugins.
- Shell-command differences between PowerShell and POSIX environments.
- Paths embedded in free-form transcript text.
- Native cross-agent transcript conversion.
Stable v0.3.0 reports privacy-safe repository, agent, capability, and runtime truth before native resume. It does not repair the environment or prove that every dependency and source file matches.