SessionHarbor

Back up, verify, reclaim, restore, and review Codex session context across macOS and Windows.

SessionHarbor is an unofficial, local-first Codex plugin and zero-dependency Node.js CLI by Xiaofan Wang. It turns an external drive or mounted NAS into a verified filesystem vault for every stable local Codex rollout.

Install with one Codex prompt

Open a new Codex task and paste the complete pinned prompt for English or 简体中文. A compact version is:

Set up SessionHarbor from https://github.com/WangPeterXF/session-harbor using the pinned v0.3.1
bootstrap prompt. Verify the owner, tag, license, and plugin before installing. Make this task my
SessionHarbor management center, start with the read-only dashboard, and do not mutate any real
session or drive without a separate explicit approval.

The setup verifies WangPeterXF/session-harbor and the pinned release before installing the repo-local marketplace plugin. Installation, destination initialization, backup publication, local cleanup, restore, and scheduling remain separate decisions.

For agents and AI tools

• AGENTS.md: repository-wide safety invariants, source map, validation, and review rules.
• docs/agent-index.md: compact task router for installation, operation, and development.
• llms.txt: small web index pointing to authoritative Markdown sources.
• llms-full.txt: generated combined context, checked for drift in CI.
• evals/plugin-discovery.json: five positive and three negative prompts for discovery precision and recall.

Project page: https://wangpeterxf.github.io/session-harbor/

SessionHarbor is source-available for noncommercial use under the PolyForm Noncommercial License 1.0.0. Commercial use requires a separate written license; see commercial licensing. Because the license restricts commercial use, SessionHarbor is not Open Source Initiative (OSI) open-source software.

Status

Version 0.3.1 implements full incremental backup, verified local cleanup, restore, cross-device continuity, a conversational management dashboard, and multi-mode scheduling. Automated validation uses synthetic Codex homes, temporary vaults, simulated interruptions, and Mac/Windows path fixtures. Each installation must still pass the physical-drive checklist before local cleanup is enabled.

SessionHarbor never edits Codex SQLite, session_index.jsonl, generated memories, authentication, or project files. It does not promise exact sidebar reconstruction. Raw JSONL remains the restore and evidence source.

The initial cross-platform validation record, Windows defects found during physical-drive testing, and remaining preview limitations are summarized in the v0.3.1 release notes.

Management task behavior

The repository includes copy-ready bootstrap prompts for Chinese and English, pinned to the official WangPeterXF/session-harbor v0.3.1 release. The prompt asks Codex to verify the pinned repository and license, add the repository marketplace, install the plugin, read the verified skill for the current chat, and turn that task into the user's long-lived SessionHarbor management center.

Official Codex behavior makes newly installed plugin skills available to new chats. The bootstrap prompt does not pretend the plugin hot-loaded: it explicitly reads the verified skill in the setup chat so that chat can continue immediately, while later chats use the normal installed plugin.

The management task starts read-only:

session-harbor dashboard --json --limit 50
session-harbor dashboard --state unbacked
session-harbor dashboard --state deleted
session-harbor dashboard --state waiting-backup-age

It reports cataloged/current/pending backups, local deletions, restorable sessions, retention waits, latest publication, and applied-backup progress. See the management-center workflow.

Backup and cleanup are independent

The settings the project exposes are deliberately separate:

{
  "backup": {
    "scope": "all",
    "allowPartial": true,
    "verifyExistingObjects": false
  },
  "retention": {
    "cleanupAfterInactiveDays": 30,
    "minimumBackupAgeDays": 7,
    "reclaimAction": "keep",
    "autoReclaim": false
  }
}

• backup.scope: always all; backup age and file size never filter disaster-recovery coverage.
• backup.allowPartial: a changing/open session is reported and retried on the next trigger while other stable sessions can still be backed up.
• backup.verifyExistingObjects: false makes insertion/weekly runs compare stable source metadata and stored object sizes, then hash only new or changed content. Set it to true for a deliberately slower full scrub; verify and restore always perform cryptographic verification.
• cleanupAfterInactiveDays: only local sessions inactive for this many days enter cleanup review.
• minimumBackupAgeDays: keep the local original for this additional safety period after its latest verified backup revision.
• reclaimAction:
  • keep keeps the local original indefinitely;
  • link replaces it with a reversible link to a stable mounted vault;
  • delete removes only the verified local original and remains restorable from the vault.
• autoReclaim: lets an explicitly installed schedule include a separate reclaim scope. It is off by default.

backup never deletes or links a local file. cleanup/reclaim is a different command. Delete mode requires both --apply and --confirm-delete-local; autoReclaim defaults to false.

Legacy config v1-v3 age/grace keys migrate into config v4. Existing reclaim actions are preserved; new configs default to keep.

Safety model

Publication follows this order:

1. Verify the destination identity marker and stable device identity.
2. Read a stable local source and compute SHA-256.
3. Copy to a same-directory temporary file, sync it, hash the stored bytes, and publish atomically.
4. Publish an immutable snapshot manifest.
5. Replace the device-owned head pointer last.

Cleanup is allowed only when the destination copy still matches the current local source, the inactivity and backup-age gates have elapsed, and the source is not open. A missing/mismatched volume, changed source, target conflict, corrupt object, symlinked path component, peer rollback, or unknown contract fails closed. Restore keeps the archive copy.

Fast scheduled backup does not replace periodic integrity verification. Run session-harbor verify manually after unsafe removal, filesystem errors, or before enabling cleanup; cleanup itself always re-hashes both local source and vault target before changing the local file.

Requirements

• Node.js 20 or newer
• A stable filesystem destination such as an exFAT external drive or mounted NAS
• macOS or Windows for the intended two-computer workflow
• Optional: codex-slim for lossless zstd compression

Use exchange.storageClass: "stable-mounted" for an external drive/NAS. iCloud, Baidu Netdisk, or another client-managed synchronized folder must use "client-synced" together with reclaim action keep; SessionHarbor rejects link/delete reclamation for that class.

Dry-run setup

Every command below is read-only until its applied form is explicitly used:

node plugins/session-harbor/scripts/session-harbor.mjs \
  init --destination /path/to/EXTERNAL_DRIVE/SessionHarbor

node plugins/session-harbor/scripts/session-harbor.mjs doctor --json
node plugins/session-harbor/scripts/session-harbor.mjs device init --json
node plugins/session-harbor/scripts/session-harbor.mjs bridge doctor --json
node plugins/session-harbor/scripts/session-harbor.mjs backup plan --json
node plugins/session-harbor/scripts/session-harbor.mjs cleanup --json

Applied destination/device initialization, first session publication, and first local reclamation are three separate approvals. See the live-readiness checklist before using a physical drive.

Backup, cleanup, and restore

After reviewing the dry-run and granting the corresponding scope:

# Preview and then incrementally back up every stable local session.
session-harbor backup plan
session-harbor backup run --apply