How to Set Up SaveState on a Fresh Machine

This is a new-user pass on a clean Node 22 install of the published package @savestate/cli at version 0.9.0. The commands below are the ones that ran, and the transcripts are the text those commands printed.

The sources followed were the README quick start (npm install -g @savestate/cli, then init, snapshot, list, restore), the docs pages, and llms.txt (npm install -g @savestate/cli, then npx -y @savestate/cli mcp). For the adapter, see Claude Code. For the client config, see MCP and Cursor.

The machine

Node came from the official tarball node-v22.23.3-linux-x64, unpacked under /tmp/ss-clean. node -v printed v22.23.3. npm -v printed 10.9.9. PATH put that Node first, then /usr/bin and /bin.

Before the install there was no ~/.npmrc, no ~/.savestate, and no global @savestate/cli. Project commands used HOME=/tmp/ss-clean/home2. The global install itself used HOME=/tmp/ss-clean/home, which also had no SaveState config. The terminal was 120 columns by 40 rows, so the spinners could finish. The passphrase was the documented example your-passphrase.

The worked example is a Claude Code project that already contains CLAUDE.md. Before init, this file was created at ~/my-ai-workspace/CLAUDE.md:

# Workspace

This project is a Claude Code workspace used to try SaveState.

Preference: cocktail recommendations should mention the glass.

Install

$ npm install -g @savestate/cli

Exit code 0. Output:

added 229 packages in 6s

64 packages are looking for funding
  run `npm fund` for details
npm notice
npm notice New major version of npm available! 10.9.9 -> 12.2.0
npm notice Changelog: https://github.com/npm/cli/releases/tag/v12.2.0
npm notice To update run: npm install -g npm@12.2.0
npm notice

The binary landed at /tmp/ss-clean/node-v22.23.3-linux-x64/bin/savestate, the prefix for this clean Node. savestate --version exited 0 and printed 0.9.0.

$ npx @savestate/cli --version

Exit code 0. The output included spinner frames, then 0.9.0, then the same npm upgrade notice as the install. The installed package.json description was Time Machine for AI. Backup, restore, and migrate your AI identity.

Init

Run in ~/my-ai-workspace, with the passphrase already exported. Elapsed 0.646 seconds. Exit code 0. Spinner frames were on the same lines as the status text.

$ export SAVESTATE_PASSPHRASE="your-passphrase"
$ npx @savestate/cli init

⚡ SaveState [U+2014] Time Machine for AI

⠋ Initializing SaveState...✔ Created .savestate/ directory
⠋ Detecting platform...✔ Detected platform: Claude Code

  Your snapshots will be encrypted with a passphrase.
  You can also set SAVESTATE_PASSPHRASE env var.


✓ SaveState initialized!

  Next steps:
  savestate snapshot      Capture your first snapshot
  savestate config        Configure storage & adapters
  savestate adapters      See available platform adapters

The banner still says Time Machine for AI. The character between SaveState and Time Machine for AI is U+2014. The transcript writes it as [U+2014].

~/my-ai-workspace/.savestate/config.json was written. storage.options.path is the absolute home directory ~/.savestate (/tmp/ss-clean/home2/.savestate). passphraseConfigured is true. The passphrase itself is not in the file. defaultAdapter is claude-code.

Save a snapshot

Elapsed 1.006 seconds. Exit code 0.

$ npx @savestate/cli snapshot --label first

⠋ Extracting state via Claude Code adapter...✔ Full snapshot created!

  ID:         ss-2026-10-20T13-43-36-6w3qby
  Adapter:    Claude Code
  Type:       full
  Label:      first
  Files:      9 files in archive
  Archive:    1.1 KB
  Encrypted:  1.2 KB
  Storage:    local
  Status:     ✓ Encrypted & stored

  Restore with: savestate restore ss-2026-10-20T13-43-36-6w3qby

The archive file is 1206 bytes:

~/.savestate/ss-2026-10-20T13-43-36-6w3qby.saf.enc

On this machine that path is /tmp/ss-clean/home2/.savestate/ss-2026-10-20T13-43-36-6w3qby.saf.enc. The project index is ~/my-ai-workspace/.savestate/index.json, and it points at that filename. The archive is not inside the project .savestate/ directory. Project .savestate/ holds config.json and index.json.

List

Elapsed 0.695 seconds. Exit code 0. The columns are ID, Date, Adapter, Label, and Size. The date is local time.

$ npx @savestate/cli list

📋 Snapshots
   Storage: local

  ID                             Date                  Adapter      Label        Size
  ───────────────────────────────────────────────────────────────────────────────────
  ss-2026-10-20T13-43-36-6w3qby  Oct 20, 13:43         claude-code  first      1.2 KB

  1 snapshot

Restore

CLAUDE.md was edited so the preference line said the recommendations should be deleted from the file. Then restore latest. Elapsed 1.03 seconds. Exit code 0.

$ npx @savestate/cli restore latest

🔄 Restoring from snapshot: latest

⠋ Retrieving and decrypting snapshot...✔ Restore complete!

  Snapshot:      ss-2026-10-20T13-43-36-6w3qby
  Timestamp:     2026-10-20T13:43:36.789Z
  Platform:      claude-code
  Adapter:       claude-code
  Label:         first
  Identity:      ✓ restored
  Memory:        0 entries restored
  Conversations: 0 indexed

  ✓ Your AI state has been restored.
  Existing files were backed up with .bak extension.

After restore, CLAUDE.md matched the file that was snapshotted. CLAUDE.md.bak held the edited text.

Connect the MCP stdio server

The Claude Code block from the MCP docs went into ~/.claude/settings.json. The Cursor block went into ~/.cursor/mcp.json. Both files were written exactly as those samples. The Claude Code file sets SAVESTATE_MCP_PASSPHRASE to your-passphrase-here. That string is the sample value. The CLI passphrase in the earlier commands was your-passphrase.

{
  "mcpServers": {
    "savestate": {
      "command": "npx",
      "args": ["-y", "@savestate/cli", "mcp"],
      "env": {
        "SAVESTATE_MCP_PASSPHRASE": "your-passphrase-here"
      }
    }
  }
}

Cursor, in ~/.cursor/mcp.json:

{
  "mcpServers": {
    "savestate": {
      "command": "npx",
      "args": ["-y", "@savestate/cli", "mcp"]
    }
  }
}

Claude Code and Cursor were not installed on this machine, so they were not restarted. The process those configs start was started directly, in ~/my-ai-workspace, with SAVESTATE_MCP_PASSPHRASE=your-passphrase-here.

$ npx -y @savestate/cli mcp

For the first two seconds, stdout was empty. stderr was:

SaveState MCP server running on stdio

A stdio client from @modelcontextprotocol/sdk 1.32.1, the copy installed with @savestate/cli@0.9.0, then called connect and listTools. That succeeded. serverInfo from the handshake:

{"name":"savestate","version":"0.5.0"}

Tools returned, four names:

• savestate_snapshot
• savestate_restore
• savestate_list
• savestate_status

The MCP docs page also lists savestate_search_snapshots, savestate_stats, the savestate_memory_* tools, and the OpenMemory-compatible names. Those names were not in this server's tools/list result. npm 0.9.0 does not expose them.

Next step: How to connect SaveState's MCP server to Claude Code and Cursor.

---

Questions? See the FAQ or open an issue on GitHub.