codex-profile-sync

简体中文 | English

codex-profile-sync safely applies a private, portable Codex source bundle on macOS, Windows, and Linux. The engine is public; your settings, named Codex profiles, MCP declarations, plugin preferences, and optional skills stay in a separate private directory or private Git repository.

The tool is deliberately one-way. It reads an already checked-out source bundle and applies declared settings to the current machine. It never runs git pull, git push, plugin installation, MCP login, or any network request.

What it manages

• 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 .

For development:

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

Create a private source bundle

Choose a directory that is not inside 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.

Source bundle format

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.

Safe file ownership

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.0 is an alpha release. The source-bundle schema is versioned, but the CLI may gain additional safe, backwards-compatible checks before 1.0.