Conservative, local-only Git checkpoints at meaningful milestones in Codex Desktop and Codex CLI workflows.
The plugin records the repository state when a user turn begins. Before Codex stops, it asks Codex to make one semantic decision: is the completed work a coherent and validated milestone? A Python safety engine then independently enforces hard gates before creating a commit.
- Never pushes, fetches, pulls, rebases, or resets the working tree.
- Never uses blind
git add .; only the evaluated changed paths are staged. - Requires a clean turn baseline by default, so existing user work is not absorbed.
- Refuses a non-empty staging area, merge conflicts, or active Git operations.
- Blocks likely credentials, private keys, files over 20 MB, whitespace errors, invalid Python, and invalid JSON.
- Runs normal Git commit hooks and restores the pre-checkpoint empty index if a hook rejects the commit.
- Supports explicit opt-out phrases such as
do not commitand不要提交.
- Codex Desktop or Codex CLI with plugin support
- Git 2.23+
- Python 3.10+
No runtime Python packages are required.
From GitHub after this repository is published:
codex plugin marketplace add Zwenpeng/codex-smart-checkpoint
codex plugin add codex-smart-checkpoint@smart-checkpointUpdate an existing GitHub installation:
codex plugin marketplace upgrade smart-checkpoint
codex plugin remove codex-smart-checkpoint@smart-checkpoint
codex plugin add codex-smart-checkpoint@smart-checkpointFrom a local clone:
./install.shOn Windows PowerShell, run ./install.ps1 instead.
Restart Codex Desktop after installation, then trust the plugin hooks when Codex asks. Hooks are deterministic local scripts and require a separate trust decision.
Open the target project in Codex and say:
Enable Smart Checkpoint in this project using smart mode.
Or run:
python "/path/to/plugin/scripts/checkpoint.py" init --repo . --mode smartThe default configuration is stored under the repository's .git directory, so it is local to your machine. Add --shared to create .codex-checkpoint.json when the whole team should use the same policy.
Modes:
smart: Codex may create a local commit after semantic and hard-gate checks.remind: report that a checkpoint is ready but never create it automatically.off: disable the hook for this repository.
Enable Smart Checkpoint for this folder.Show the checkpoint status and explain any blocker.List checkpoints created for this project.Restore src/app.py from checkpoint a1b2c3d4 without committing.Revert checkpoint a1b2c3d4 with a new inverse commit.Do not commit this turn.
Copy plugins/codex-smart-checkpoint/templates/checkpoint.json to .codex-checkpoint.json for a shared policy. allow_paths and deny_paths use Git-style forward-slash paths with shell wildcard matching.
The plugin intentionally does not execute arbitrary test commands from repository configuration. Codex must run the relevant project tests during the task, then decide whether the result is stable. This avoids turning a cloned repository's configuration into automatic code execution.
python "/path/to/plugin/scripts/checkpoint.py" list --repo .
python "/path/to/plugin/scripts/checkpoint.py" show --repo . REV
python "/path/to/plugin/scripts/checkpoint.py" restore --repo . REV -- path/to/file
python "/path/to/plugin/scripts/checkpoint.py" revert --repo . REVrestore refuses to overwrite a currently modified target. revert requires a clean working tree and only accepts commits carrying the Smart Checkpoint trailer.
./uninstall.shOn Windows PowerShell, run ./uninstall.ps1 instead.
Project configuration and Git commits remain. Delete .codex-checkpoint.json or .git/codex-smart-checkpoint/config.json only if you also want to remove project settings.
python -m unittest discover -s tests -v
python -m py_compile plugins/codex-smart-checkpoint/scripts/*.py plugins/codex-smart-checkpoint/hooks/*.pySee CONTRIBUTING.md, SECURITY.md, and PRIVACY.md.
For usage problems, read SUPPORT.md before opening an issue.
MIT