codex-session-share

Safely share only local Codex session history across two or more isolated CODEX_HOME directories. Authentication, configuration, plugins, caches, memories, attachments, and generated assets remain separate.

This is an independent community utility, not an official OpenAI project.

Why

Codex discovers resumable sessions inside the active home. Switching CODEX_HOME therefore switches both credentials and the visible local session store. This tool merges existing session trees and replaces only each sessions directory with a symlink to a shared store.

~/.codex-a/sessions ───┐
                       ├──▶ ~/.local/share/codex-sessions
~/.codex-b/sessions ───┘

~/.codex-a/auth.json       remains private to account A
~/.codex-b/auth.json       remains private to account B

New requests always use the credentials from the selected CODEX_HOME. A shared transcript does not share an account or transfer billing history.

Safety model

• Dry-run by default; mutation requires --apply.
• Refuses fewer than two homes, duplicate homes, broad paths, missing session directories, existing shared targets, and nested symlinks.
• Hashes same-path files and aborts on different content instead of choosing a winner silently.
• Copies into a staging directory before renaming any source.
• Preserves every original tree as a timestamped backup.
• Writes a mode-0600 JSON recovery manifest.
• Uses a non-blocking OS file lock to prevent concurrent migrations targeting the same shared parent directory.
• Rolls back partial link/rename work if migration fails.
• Rollback restores original trees while retaining the merged store, so sessions created after migration are not deleted.
• Never reads or copies authentication files.

The principal residual risk is an active Codex writer. Close all Codex CLI, IDE, and desktop sessions before applying or rolling back. Session transcripts may contain sensitive prompts and outputs; choose a shared location accessible only to your operating-system user and do not put it in cloud sync or Git.

Install

Requires Python 3.10+ on macOS or Linux.

python3 -m pip install .

For isolated installation, pipx install . is recommended when pipx is available.

Use

Preview first:

codex-session-share plan \
  --home "$HOME/.codex" \
  --home "$HOME/.codex_work" \
  --shared "$HOME/.local/share/codex-sessions"

Close every Codex process, then apply:

codex-session-share share \
  --home "$HOME/.codex" \
  --home "$HOME/.codex_work" \
  --shared "$HOME/.local/share/codex-sessions" \
  --apply

Inspect without reading transcript contents:

codex-session-share status \
  --home "$HOME/.codex" \
  --home "$HOME/.codex_work"

The share command prints a recovery-manifest path. To undo the links and restore each original session tree:

codex-session-share rollback \
  --manifest "$HOME/.local/share/migration-YYYYMMDDTHHMMSSZ.json" \
  --apply

The merged shared directory is intentionally retained after rollback. Inspect it before deciding whether to archive or remove it.

What is deliberately not shared

• auth.json, API keys, OAuth grants, or other credentials
• config.toml and account-specific policy
• plugins, skills, rules, and MCP configuration
• caches, logs, shell snapshots, memories, attachments, and generated images

An old transcript can refer to an attachment that exists only in its original home. Sharing attachments would expand the privacy and consistency boundary, so this project does not do it automatically.

Development

python3 -m unittest discover -s tests -v
python3 -m compileall -q src tests

See SECURITY.md for the threat model and responsible disclosure instructions.

Compatibility

This utility relies on the current local CODEX_HOME/sessions convention. That layout is an implementation detail and may change. Always run plan and keep the generated backups when upgrading Codex or this tool. See the official Codex CLI reference and Codex configuration documentation.