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.1.0-rc.8
- Release status
- pre-1.0 release candidate
- 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. RC8 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
macOS native and Windows 11 native are primary Phase 1 targets. Current source compatibility evidence covers macOS arm64 plus deterministic synthetic fixtures. Native Windows acceptance, macOS amd64, WSL2 smoke coverage, and physical two-device resume remain release gates before stable v0.1 certification.
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.
Environment fingerprinting and verified resume are later roadmap phases. RC8 restores supported native session state and structural paths; it does not yet prove that every part of the coding environment matches.