codex-profile-sync

简体中文 | English | Changelog

Keep the same Codex setup when you move to another Mac, Windows PC, or Linux machine. codex-profile-sync reads a private source bundle and applies only the settings and files you explicitly declare.

The engine can stay public while your configuration remains in a separate private directory or private Git repository. The tool does not run Git, install plugins, sign in to MCP servers, or make network requests.

What moves between machines

• Explicitly declared keys in $CODEX_HOME/config.toml (default: $HOME/.codex/config.toml).
• Named Codex profile files such as review.config.toml under CODEX_HOME.
• Optional user skills under $HOME/.agents/skills, with ownership tracked by content hashes.

It never manages authentication, OAuth state, history, sessions, logs, SQLite databases, caches, memories, plugin caches, or any other Codex runtime state. See the threat model for the complete boundary.

The paths above follow the current official Codex documentation for configuration profiles and user skills.

Install

Python 3.11 or newer is required.

pipx install codex-profile-sync
# or
uv tool install codex-profile-sync

For development from a source checkout:

python -m pip install -e '.[dev]'

First use

Create the private bundle outside this public engine checkout:

codex-profile-sync init "$HOME/private-codex-profile"

The command creates files but does not initialize Git or configure a remote. If you use Git to carry the bundle across machines, keep that repository private and update it yourself before applying:

git -C "$HOME/private-codex-profile" pull --ff-only
codex-profile-sync plan --source "$HOME/private-codex-profile"
codex-profile-sync apply --source "$HOME/private-codex-profile"

Review the plan before applying. apply prompts by default; use --yes only in controlled automation.

Configure the bundle

Every bundle contains sync.toml:

schema_version = 1
profile_id = "portable-codex"

[config]
common = "config/common.toml"
platform_dir = "config/platforms"
managed_paths = ["model_reasoning_effort", "plugins.*", "mcp_servers.*"]
remove_paths = []

[named_profiles]
directory = "profiles"

[skills]
directory = "skills"
enabled = false

Portable values go in config/common.toml. Platform overlays go in config/platforms/macos.toml, windows.toml, and linux.toml; the selected overlay wins over common values.

managed_paths is an allowlist. Exact paths manage a scalar or table. The only supported wildcards are plugins.* and mcp_servers.*; they expand to the specific entries present in the source files. Undeclared local configuration is preserved, including comments.

remove_paths is the only explicit deletion interface. A value can be removed only when this profile previously managed it and the local value still matches the recorded hash. Removing an entry from managed_paths merely relinquishes ownership.

Protected runtime-owned areas—including project trust, plugin marketplace paths, desktop runtime settings, and mcp_servers.node_repl—cannot be managed.

Commands

codex-profile-sync init <source-dir>
codex-profile-sync plan --source <dir> [--platform auto|macos|windows|linux]
codex-profile-sync apply --source <dir> [--yes]
codex-profile-sync doctor --source <dir>

plan, apply, and doctor also accept --codex-home and --json.

Exit codes are:

• 0: successful and, for doctor, fully synchronized.
• 1: invalid input or operational failure.
• 2: doctor found safe-to-apply drift.
• 3: a conflict requires manual resolution.

JSON plans expose only action names and paths, never configuration values.

Conflicts, backups, and rollback

Named profiles and skills use a local state file in the platform's application state directory. An existing identical file can be adopted. A different unregistered file is never overwritten. Once managed, a file is updated or deleted only while its content still matches the previous hash; local edits become conflicts.

Source and target symlinks are rejected. Writes are atomic, existing files are backed up outside both repositories, and a failed multi-file apply attempts to restore every changed target.

Development

pytest
ruff check .
python -m build
python scripts/audit_public_tree.py .

Tests use temporary home and state directories and never touch the developer's real Codex configuration.

Status

Version 0.1.1 is an alpha release. The source-bundle schema is versioned, but the CLI may gain additional safe, backwards-compatible checks before 1.0.