reinstate

README

Reinstate

Find and continue coding-agent work across sessions and devices

Reinstate is an open-source tool that finds local coding-agent sessions and syncs supported Claude Code and Codex sessions through your own encrypted S3-compatible storage.

Stable v0.2.0 adds a configless local session index, literal search, metadata inspection, a numbered switcher, and same-vendor native resume/fork. Apple Silicon macOS and native Windows x64 passed the complete physical matrix. Intel macOS and Linux/WSL2 downloads remain preview/unverified pending issues #97 and #98.

Current release candidate v0.3.0-rc.4 adds Phase 3 verified resume. Its tagged-artifact acceptance on Apple Silicon macOS and native Windows x64 is pending; it is not stable v0.3.0.

Why · Features · Quick start · Agents · How it works · Docs · Roadmap · Contributing

_{Created & maintained by Harjot Singh Rana · harjot.co}

---

The problem

Even on one machine, you can have twenty sessions across Claude Code, Codex, projects, branches, and worktrees. Finding the right thread later becomes a memory problem.

Then you open your MacBook on the couch.

Git has the code. The agent does not have the conversation — the rejected approaches, the files already read three times, the style constraints you established mid-thread. Vendor tools save sessions locally. Switching machines is context death.

flowchart LR
  subgraph Desktop["🖥️ Desktop (Windows)"]
    D["20 sessions<br/>full context"]
  end
  subgraph Laptop["💻 Laptop (macOS)"]
    L["empty history<br/>MCP + skills B<br/>start from zero"]
  end
  D -.-x|context dies| L
  style D fill:#1f2937,stroke:#f87171,color:#f9fafb
  style L fill:#1f2937,stroke:#f87171,color:#f9fafb

Reinstate makes state portable:

flowchart LR
  subgraph Desktop["🖥️ Desktop"]
    A["Claude/Codex sessions"]
  end
  subgraph Cloud["☁️ Encrypted cloud"]
    B["your R2 / S3-compatible bucket<br/>ciphertext only"]
  end
  subgraph Laptop["💻 Laptop"]
    C["resume · same IDs"]
  end
  A -->|push · age E2E| B
  B -->|pull · remap paths| C
  style A fill:#064e3b,stroke:#34d399,color:#ecfdf5
  style B fill:#0c4a6e,stroke:#22d3ee,color:#e0f2fe
  style C fill:#312e81,stroke:#818cf8,color:#e0e7ff

---

Why Reinstate?

	What you get
Local recovery	Configless local index/search/resume for Claude Code and Codex
Multi-agent	One metadata index; native execution always stays with the source vendor
Verified resume	v0.3.0-rc.4 checks the workspace, agent, capabilities, and recognized runtimes before launch
Offline-capable origin	Works when the other machine is off (stored sync, not a live relay)
Path remapping	Windows ↔ macOS project paths rewritten so --resume actually finds sessions
Zero-knowledge	Client-side encryption; bring-your-own storage
Bounded previews	Metadata and a short user-prompt preview, never a default transcript dump
Privacy-safe environment truth	Capability names and state may be indexed; contents, commands, values, credentials, and raw URLs are excluded
Open source	Apache-2.0 · auditable · patent grant · no vendor lock-in

Native vendor sync typically serves its own ecosystem. Unreviewed Syncthing/Drive copies can preserve source-device absolute paths or include sensitive artifacts. Reinstate instead provides Claude/Codex same-vendor × cross-device × encrypted × path-aware continuity.

---

Features

Stable v0.2.0:

• Configless local index — rein sessions works without init or cloud storage
• Literal search — prompt, file, branch, project, agent, and session identity
• Metadata-first inspect — bounded user-prompt preview; no full transcript mode
• Native continuation — last, resume, and fork launch the source vendor
• Interactive switcher — bare rein on a TTY; deterministic JSON for automation
• Read-only expansion — Gemini CLI and OpenCode discovery without mutation

Included in the v0.3.0-rc.4 release candidate (tagged-artifact acceptance pending):

• Verified resume — deterministic environment reports on inspect, native dry-runs, direct launches, last, and picker selections
• Workspace truth — offline repository identity, branch, HEAD, and privacy-safe working-tree checks without fetching or printing filenames
• Agent and capability checks — fail-closed Claude/Codex version and layout verification plus bounded, name-only instruction, skill, and MCP inventory
• Runtime checks — recognized Node and Go declarations inspected without running project scripts
• Exact authorization — warnings require terminal confirmation or every invocation-scoped --allow-environment-warning CHECK_ID; blockers cannot be overridden

Also included from stable v0.1.0:

• Cross-device session sync — continue the same Claude/Codex thread on another machine
• Multi-agent adapters — same-vendor Claude Code and Codex session continuity
• End-to-end encryption — age, passphrase-derived keys
• Bring-your-own storage — Cloudflare R2, AWS S3, and S3-compatible storage
• OS-aware path remapping — the hard problem treated as the product
• Safe by default — credential denylist, atomic restore, conflict forks, local backups
• Simple sync CLI — rein init · push · pull · status · diff · conflicts (rein is the short alias; reinstate is the full command — same binary)

Later, Reinstate will extend continuity beyond sessions: declare MCP servers, skills, hooks/loops, plugins, marketplaces, instruction files, and safe settings once, then preview and apply the correct native configuration across Claude Code, Codex, Grok, OpenCode, Gemini CLI, and multiple devices. This is planned, not part of the current CLI. See Universal agent configuration.

---

Quick start

Platform boundary: the public installers pin candidate v0.3.0-rc.4. Tagged-artifact acceptance is pending on Apple Silicon macOS and native Windows x64. Stable remains v0.2.0; Intel macOS and Linux/WSL2 remain optional and unverified for RC4.

CLI: prefer short alias rein. Full name reinstate works the same.

Local continuity from the current source

From this repository, with Go 1.25.12 or newer:

make build
export REINSTATE_HOME="$HOME/.reinstate-phase3-local"

./bin/rein sessions
./bin/rein search "stripe webhook retry" --agent claude
./bin/rein inspect claude:SESSION_ID
./bin/rein last --dry-run
./bin/rein resume codex:SESSION_ID --dry-run
./bin/rein fork claude:SESSION_ID --dry-run
./bin/rein

On native Windows PowerShell, build .\bin\rein.exe with go build -o .\bin\rein.exe .\cmd\reinstate, set $env:REINSTATE_HOME, and use that executable for the same commands.

These commands refresh a private derived index at $REINSTATE_HOME/cache/session-index-v2.sqlite. Its owner-only .lock and .write.lock files protect destructive repair and serialize writers/rebuilds across concurrent rein/reinstate processes. None is synced. These commands do not require init, storage credentials, a passphrase, or a network backend.

The v0.3.0-rc.4 candidate adds an environment report to inspect and native dry-runs. A first launch truthfully warns with baseline.unavailable; it never manufactures a historical match. Review the report, then either confirm on a TTY or acknowledge every current warning explicitly in automation:

./bin/rein resume claude:SESSION_ID \
  --allow-environment-warning baseline.unavailable

Acknowledgements apply only to that invocation. Missing workspaces, unrecognized agent versions/layouts, known repository replacement, stale source metadata, and verifier failures remain non-overridable. A private reinstate_prelaunch_observed baseline is stored only after the authorized same-vendor child exits successfully. Native resume/fork remains same-vendor.

Bare rein opens the numbered switcher only on a TTY. For scripts use rein sessions --json; a non-TTY bare invocation exits promptly with that hint.

Install stable v0.2.0 with Homebrew

Apple Silicon macOS with Homebrew:

brew install HarjjotSinghh/tap/reinstate

The tap's stable formula passed install, both-alias identity, formula test, no-op upgrade, and uninstall checks on Apple Silicon. Intel macOS and Linuxbrew remain unverified for v0.2.0.

Install the v0.3.0-rc.4 candidate

These public bootstrap routes install the candidate, not the stable Homebrew formula. RC4 tagged-artifact acceptance is pending.

macOS, Linux, or WSL2:

curl -fsSL https://reinstate.dev/install.sh | sh

Native Windows PowerShell:

irm https://reinstate.dev/install.ps1 | iex

Both bootstraps pin and verify v0.3.0-rc.4, install without elevation, and print the next command:

rein version --json
rein init

Reinstate waits at most 30 seconds for replacement approval; set REINSTATE_CONFIRM_TIMEOUT_SECONDS=1..300 to choose a shorter or longer bound. Shells without timed-read support refuse immediately and preserve the installed binary. For deliberate automation, review the version change first and set REINSTATE_CONFIRM_REPLACE=1.

Optional encrypted sync — Device A

rein init --project github.com/acme/app=/absolute/path/to/app
rein list --agent AGENT
rein push --agent AGENT --session SESSION_ID --dry-run
rein push --agent AGENT --session SESSION_ID

Use the S3/R2 service endpoint as the endpoint and enter the bucket separately. Reinstate refuses to overwrite an initialized home by default. The explicit --force path backs up prior config and state together before replacement.

Optional encrypted sync — Device B

rein init --profile-id <DEVICE_A_PROFILE_ID> \
  --project github.com/acme/app=/different/local/path
rein status
rein pull --agent AGENT --session SESSION_ID --dry-run
rein pull --agent AGENT --session SESSION_ID
# Then use the same vendor's native resume UI or command.

Reinstate verifies the encrypted remote manifest during additional-device init before saving local configuration. Require status to show the expected sessions after setup.

Full walkthrough: docs/getting-started.md

---

Supported agents

Agent	Local index	Resume/fork	Encrypted sync	Status
Claude Code	✅ full	✅ native	✅	Stable on Apple Silicon macOS and native Windows x64
OpenAI Codex CLI	✅ full	✅ native	✅	Stable on Apple Silicon macOS and native Windows x64
Gemini CLI	✅ read-only	—	—	Physical read-only path passed on Windows; unavailable on test Mac
OpenCode	✅ read-only	—	—	Physical read-only path passed on Windows; unavailable on test Mac
Grok Build	📋	—	—	Later phase

Details: docs/adapters.md

---

How it works

flowchart TB
  subgraph Agents["Coding agents on disk"]
    CC[Claude Code]
    CX[Codex]
    GM[Gemini CLI]
    OC[OpenCode]
  end
  subgraph Local["Local continuity · no config/cloud"]
    AD[Read adapters]
    IX[Private derived index]
    Q[Search · inspect · switcher]
    EX[Same-vendor launch plan]
  end
  subgraph Sync["Optional encrypted sync"]
    NM[Normalize paths]
    EN[Encrypt · age]
    SY[Manifest · push/pull]
  end
  BK[(Your bucket<br/>R2 / S3-compatible)]
  Agents --> AD --> IX --> Q --> EX --> Agents
  Agents --> NM --> EN --> SY
  SY <-->|ciphertext only| BK
  SY -->|pull · decrypt · remap · atomic restore| Agents

1. Local read adapters derive bounded metadata and user-prompt search text
2. Index stores owner-only SQLite session rows and private prelaunch baselines; it never enters sync
3. Verified resume (current source) observes the fresh workspace, agent, capabilities, and runtimes and applies exact warning/blocker policy
4. Executors launch a supported session through its native vendor
5. Pathmap rewrites known structural paths for optional cross-device sync
6. Crypto/sync encrypt before upload and restore atomically with backups

Deep dive: docs/architecture.md · research diagram:

---

Security

Guarantee	Detail
E2E encryption	Ciphertext only on remote storage
Credential denylist	auth.json and tokens never synced by default
Private local index	Owner-only derived metadata; no assistant/tool-output corpus
No vendor API keys required	Local files only
Verified-resume boundary	Offline checks, exact warning consent, non-overridable blockers
Fail-safe restore	Backups + conflict forks

Report vulnerabilities privately: SECURITY.md · model: docs/security-model.md

---

Documentation

Doc	Description
Website	reinstate.dev — product, documentation, compatibility, and security
Getting started	Configless local index plus optional encrypted sync
Verified resume	Phase 3 environment report, provenance, policy, and privacy contract
Architecture	Pipeline, packages, design principles
Adapters	Per-agent layouts & support matrix
Universal configuration	Planned MCP/skills/loops/plugins/settings portability
Security model	Threat model & defaults
Comparison	vs native sync, claude-sync, DIY
FAQ	Common questions
Troubleshooting	Path remap, conflicts, large histories
Roadmap	Phases & non-goals
Contributing	Dev setup & PR process
Releasing	Maintainer release checklist
Package-manager publishing	Maintainer registry rollout and authentication guide
Support	How to get help
Governance	Decision making
Changelog	Release history

---

Project activity

Star history

↗ Open interactive star history · Stargazers

Contributors

Category context

Insights

Metric	Link
Pulse	pulse
Traffic	graphs/traffic
Commits	graphs/commit-activity
Code frequency	graphs/code-frequency
Network	network
Stars	stargazers · star-history

---

Roadmap

Phase	Focus	Status
0	Contracts, diagnostics, installers, fixtures, release trust	✅
1	Claude + Codex encrypted same-vendor session sync	✅
2	Configless local index, search, native resume/fork	✅
3	Verified resume (included in v0.3.0-rc.4; tagged-artifact acceptance pending)	🚧
4	Portable handoffs	📋
5–7	Universal config + automatic sync, thin Console/ACP client, teams	📋 / 💭

Full detail: ROADMAP.md

---

Stable releases

Channel	Tag	Notes
Latest		Stable builds
Pre-release		Early adopters
SemVer	pre-1.0	Breaking changes possible in minors — see CHANGELOG

Install from GitHub Releases. Every published release must include checksums, SBOMs, a source archive, and an artifact attestation.

---

Maintainers

Lead	Harjot Singh Rana (@HarjjotSinghh)
Site	harjot.co
X	@HarjjotSinghh

See MAINTAINERS.md · AUTHORS · CODEOWNERS

---

Contributing

Contributions are welcome — code, adapters, docs, and bug reports.

1. Read CONTRIBUTING.md and the Code of Conduct
2. Open an issue for larger changes
3. Fork → branch → PR

make deps && make test && make build

Good first issues: good first issue

---

Community & support

• Questions — open a redacted question issue
• Bugs / features — Issues
• Security — SECURITY.md (private)
• Support guide — SUPPORT.md

---

Citation

If you use Reinstate in research or publications:

@software{rana_reinstate_2026,
  author = {Rana, Harjot Singh},
  title  = {Reinstate: Encrypted multi-agent session sync for AI coding tools},
  year   = {2026},
  url    = {https://github.com/HarjjotSinghh/reinstate},
  license = {Apache-2.0}
}

Also see CITATION.cff.

---

License

Licensed under the Apache License, Version 2.0 © 2026 Harjot Singh Rana.

Copyright 2026 Harjot Singh Rana

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

See NOTICE for third-party acknowledgements. Product names of third-party agents are trademarks of their respective owners; Reinstate is an independent project and is not affiliated with or endorsed by those vendors.

---

Work on desktop. Resume on laptop. Keep the context.

_{Built with ☕ in New Delhi · Open source forever}