codex-sync

codex-sync synchronizes local Codex chats per Git repository between Windows and Linux. It stores rollout JSONL files and portable metadata in a shared directory such as Google Drive, then creates machine-local rollout copies and updates the local Codex thread index with the current machine's paths.

Git remains responsible for source code. codex-sync records a normalized repository identity and clickable web link, but it never uploads or copies repository files.

It deliberately does not synchronize state_5.sqlite, its WAL files, credentials, logs, memories, or the rest of ~/.codex.

Requirements

• Node.js 22.16 or newer
• Git
• A locally synchronized folder such as Google Drive

The package has no third-party runtime dependencies.

Install

Directly from GitHub:

npm install --global github:amanmamgain9/codex-sync

From a local checkout:

npm install --global .

After an npm release, the scoped-package command will be:

npm install --global @bigbeachdaddy/codex-sync

Configure

Point the CLI at the locally synchronized shared folder, then initialize each checkout once.

PowerShell:

$env:CODEX_SYNC_ROOT = "$env:USERPROFILE\My Drive\CodexSessions"
codex-sync init
codex-sync status
codex-sync sync

Linux:

export CODEX_SYNC_ROOT="$HOME/GoogleDrive/CodexSessions"
codex-sync init
codex-sync status
codex-sync sync

codex-sync init finds the Git root, normalizes origin, converts SSH remotes into clickable HTTPS links, and writes .codex-sync.json:

{
  "format_version": 1,
  "repo_id": "github.com/company/project",
  "repo_url": "https://github.com/company/project"
}

The file contains no credentials and is safe to commit. A repository without a remote must provide an explicit identity. Add --repo-url when that identity should also have a clickable link:

codex-sync init --repo-id company/project --repo-url https://git.example.com/company/project

Usage

Run from the repository whose chats you want to synchronize:

codex-sync init
codex-sync status
codex-sync push
codex-sync pull
codex-sync sync
codex-sync sync --dry-run
codex-sync sync --sync-root "/path/to/Google Drive/CodexSessions"
codex-sync --help

• init records the repository identity and clickable URL; it does not copy source files.
• status compares local and shared sessions without writing.
• push exports new or newer local sessions.
• pull imports new or newer shared sessions.
• sync safely performs both directions and remains the default command.

Conversations started from subdirectories inside a repository belong to the same repository scope. Branches and worktrees with the same normalized remote also share that scope.

Shared layout:

CodexSessions/
  github.com-company-project-<hash>/
    repo.json
    sessions/<session-id>.jsonl
    metadata/<session-id>.json

repo.json contains only portable repository metadata such as repo_id, repo_url, and a credential-free remote URL. Session sidecars also include repo_url, allowing a Codex plugin or other UI to display a direct repository link.

During import, codex-sync:

1. Copies the shared rollout into the date-based local ~/.codex/sessions/ layout.
2. Rewrites only the copied rollout's initial session_meta.cwd to the current repository path.
3. Creates a timestamped online backup of state_5.sqlite.
4. Transactionally inserts or updates the thread row using columns present in the installed Codex schema.

Imported chats should then be associated with the project in Codex Desktop and available by session ID to codex resume. Refresh or restart Codex if the project sidebar was already open.

Conflict behavior and safety

• Newer session metadata wins; this is session-level synchronization, not line-level merging.
• Equal-time divergent copies stop with an explicit conflict instead of overwriting either copy.
• Windows/Linux cwd differences are excluded from the session comparison hash.
• Run synchronization after a chat turn completes. Do not edit the same chat concurrently on two machines.
• Shared files are published with atomic replacement.
• The SQLite database remains local and is backed up before import.
• The CLI never deletes shared or local sessions.
• Running outside Git fails with E_REPO_NOT_FOUND rather than synchronizing an accidental directory.
• A repository without origin or an explicit identity fails with E_REPO_REMOTE_MISSING.
• Pulling a repository that has never been pushed fails with E_SHARED_REPO_NOT_FOUND and explains how to recover.
• Remote network reachability is not required during filesystem synchronization; a private, deleted, or temporarily unreachable web remote does not invalidate a local Git checkout.
• Rollouts can contain prompts, responses, code, paths, and tool output. Protect the shared folder accordingly.

Codex's local storage format is not documented as a stable public integration API. Test imports after Codex upgrades; schema-aware writes reduce compatibility risk but cannot eliminate it.