agent-state-migrator

Provider-based CLI for migrating local AI coding workspace state across Macs. It treats tools like Codex and Claude as pluggable providers and uses manifest-driven backup, verification, diff, and restore workflows so migrations stay inspectable, portable, and auditable.

Current providers:

• codex
• claude

Profiles:

• minimal: settings, skills, steering, hooks, lightweight preferences
• full: minimal profile plus sessions, history, plans, todos, project metadata, and selected desktop state

Backups are stored as a normal directory:

• manifest.json
• payload/...

That format is intentionally inspectable, portable, and easy to wrap with a GUI later.

Why this structure

This project is designed as a migration engine rather than a one-off copy script:

• provider modules describe app-specific paths
• profile and sensitivity policies are separate from provider definitions
• manifest files use $HOME/... path templates so restores work across different macOS usernames
• optional checksums support integrity verification
• diff and verify make the backup auditable

Commands

List providers

node src/cli.js providers

List profiles

node src/cli.js profiles

Inspect current machine

node src/cli.js inspect --profile full --target codex,claude --with-metadata

Create a backup

node src/cli.js backup \
  --profile full \
  --target codex,claude \
  --include-sensitive \
  --with-checksums \
  --output /tmp/agent-state-full

Verify backup integrity

node src/cli.js verify --input /tmp/agent-state-full

Compare a backup against a machine

node src/cli.js diff --input /tmp/agent-state-full --target-home "$HOME"

Restore into a machine

node src/cli.js restore --input /tmp/agent-state-full --target-home "$HOME" --force

Manifest format

The manifest includes:

• tool version and manifest version
• selected providers and profile
• source machine metadata
• source path templates
• per-artifact metadata:
  • type
  • size
  • file and directory counts
  • optional sha256 checksum

This is enough to support:

• reproducible restore targets
• audit-friendly backup review
• integrity verification of the payload
• machine-to-backup diffing

Safety model

• --dry-run: simulate backup or restore without copying files
• --include-sensitive: include auth-adjacent and browser-like state
• --force: allow overwrite of existing output directories or restore targets
• restore performs conflict detection before copying unless --force is used

Architecture

• src/providers/: provider definitions
• src/profiles.js: profile model
• src/policies.js: sensitivity policy
• src/operations.js: backup, restore, verify, diff workflows
• src/checksum.js: file and tree metadata collection

Notes

• SQLite files are backed up with matching -wal and -shm sidecars when present.
• By default, sensitive items are excluded.
• Different app versions may still require re-login or minor repair after restore.