English | 简体中文

codex-session-sync

This repository publishes codex-session-sync, an open-source Codex skill for repeatable offline synchronization of incoming Codex session packages into a local Codex Desktop environment.

As AI sessions become longer-lived and more operationally important, session portability is no longer only about copying a conversation once. In practice, the same logical conversation lineage may be packaged more than once, delivered to the same machine more than once, and continue evolving on both sides over time.

That creates a harder problem than one-time transfer. The local Codex environment may already contain an earlier import of the same lineage. Some sessions may be unchanged, some may only need a fast-forward update, and some may have diverged after sharing a common history. In those cases, a plain installer is no longer enough.

codex-session-sync was developed to solve that repeated-import problem while preserving compatibility with codex-session-transfer. It reuses the transfer/localization model for incoming offline packages, but adds lineage-aware matching, legacy adoption, fast-forward import, divergence preservation, sidecar reconstruction, and rollback-aware sync journaling.

This capability is useful when teams exchange updated Codex work packages across machines, when one operator repeatedly receives refreshed session bundles from another environment, when long-running session histories need to be consolidated without losing branch structure, and when local Codex state must be repaired after rollback or broader environment restoration.

Workflow at a Glance

flowchart LR
    A["Incoming offline session package"] --> B["Inspect package and classify sessions"]
    B --> C["Adopt legacy transfer-only sessions when needed"]
    C --> D["Choose sync action per session"]
    D --> E["Skip unchanged sessions"]
    D --> F["Fast-forward matching local sessions"]
    D --> G["Import new lineages"]
    D --> H["Preserve divergence as a new local branch"]
    F --> I["Record transaction and sidecar updates"]
    G --> I
    H --> I
    I --> J["Allow rollback, sidecar rebuild, and transaction replay"]

Loading

Step 1. Receive an Offline Package

An incoming package is delivered to the local machine. codex-session-sync does not assume a live remote protocol; it only operates on a local package directory or archive that has already arrived.

Step 2. Inspect and Match Sessions

The skill inspects package metadata, reuses transfer-compatible package interpretation, and matches incoming sessions against known local lineage state, sidecar mappings, and transcript fingerprints.

Step 3. Adopt Legacy Local Sessions When Needed

If a session had previously been imported only through codex-session-transfer, codex-session-sync can adopt it by creating sync-owned sidecar metadata without changing the transcript's core semantics.

Step 4. Execute the Right Sync Action

Per session, the skill may:

• skip unchanged content
• fast-forward a known local session
• import a new lineage
• preserve a divergence by creating a new local branch session

Step 5. Recover and Rebuild State

The skill records sync transactions, supports targeted rollback paths, and can rebuild sidecar state after broader local restoration events.

What It Does

• Inspect an incoming offline session package before writing
• Reuse transfer-compatible package loading and localization behavior
• Adopt transfer-only local sessions into sync lineage tracking
• Classify sessions as new_lineage, unchanged, fast_forward_import, diverged_lineage, or id_collision_unrelated
• Execute safe sync actions for new_lineage, fast_forward_import, and diverged_lineage
• Record sync transactions for audit and rollback
• Rebuild sidecar state and replay transaction history after recovery events

Skill Name vs Repository Name

The GitHub repository and the installable skill both use the name codex-session-sync, as defined in SKILL.md. When you install it into Codex, place the folder at:

~/.codex/skills/codex-session-sync/

Repository Layout

codex-session-sync/
  SKILL.md
  agents/
    openai.yaml
  references/
    cli-shape.md
    common-interfaces.md
    compatibility-contract.md
    conflict-decision-matrix.md
    sync-sidecar-schema.md
    upgrade-roadmap.md
  scripts/
    sync_extension_points.py
    sync_session_skill_package.py
  tests/
    test_sync_extension_points.py
  README.md
  README.zh-CN.md
  PUBLISHING.md
  LICENSE
  .gitignore

Primary Workflow

This skill currently provides one offline sync lifecycle with these operator-facing actions:

• inspect-package
• sync
• adopt
• list-transactions
• rollback
• sidecar-health
• rebuild-sidecar
• prune-invalid-mappings
• replay-transactions-sidecar

The main implementation lives in scripts/sync_session_skill_package.py.

Relationship to codex-session-transfer

codex-session-transfer remains the first-import and localization workflow.

codex-session-sync is the repeat-import and reconciliation workflow that sits on top of that foundation. It is intentionally designed to remain compatible with transfer-produced packages and transfer-processed local sessions.

Read these documents before modifying that boundary:

• references/compatibility-contract.md
• references/common-interfaces.md
• references/upgrade-roadmap.md

Current Scope

This repository currently focuses on the repeat-import offline sync layer for the first-phase minimum working set:

• rollout jsonl files
• threads
• session_index
• thread_dynamic_tools
• sync sidecar lineage and mapping state
• sync transaction manifests and rollback metadata

It already supports exercised execute paths for:

• new_lineage
• fast_forward_import
• diverged_lineage

Planned next upgrades are documented in references/upgrade-roadmap.md, including:

• making new_lineage rollback less dependent on transfer's lower-level replay
• enriching transaction replay for new_lineage
• expanding automated tests

License

This repository is released under the MIT License.