codex-keysmith: A Dry-Run-First Deployer for Codex Global Instructions
Version-independent Codex instruction deployment with dry-run, backups, hook isolation, and recovery.
At a glance
- What is it?
- codex-keysmith installs a Markdown instruction file into Codex's global config with previews, backups, hook isolation, and rollback. It is aimed at users who need reversible, version-independent control over their Codex setup.
- Who is it for?
- Adopt codex-keysmith if you manage Codex globally and need a reversible, preview-first way to install an instruction file and isolate hooks. Skip it if you prefer project-level instruction imports (Claude Code style) or if you run Windows in production, since fresh deployments there are explicitly beta.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 48 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 14, 2026, and from our analysis. They are not legal advice.
Star history
- Jia-Ethan/codex-keysmith4,804 ★ · +2,736
| Repository | 2026-07-29 | 2026-11-14 |
|---|---|---|
| Jia-Ethan/codex-keysmith | 2.1k | 4.8k |
2,736 Stars in the last 108 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
What codex-keysmith solves
Editing Codex's instructions by hand is risky: a mistake changes behavior across every new session. codex-keysmith addresses that by turning deployment into a three-step ritual: preview, confirm, write. The README is explicit that it changes the conversations opened afterwards under that Codex configuration. It targets users who run Codex locally and need a repeatable way to install or swap instruction sets without losing track of what changed.
The deployment mechanism
The tool deploys an instruction file into a local Codex configuration directory, such as the ~/.codex passed with --codex-dir in the README's examples. It does not change the Codex software itself and does not read accounts or keys, and by default it installs a single draft. The repository's examples/ directory holds instruction files such as gpt-unrestricted.md, gpt-lean.md and gpt-contract.md. The README warns that the change applies to conversations opened afterwards under that Codex configuration, so you need to start a new task after installing.
Running it: commands and flags
Installation is not via pip. You download a single-file release asset, codex-instruct-v0.6.0.py, plus SHA256SUMS, and verify the checksum with shasum -a 256 -c. After verification, you run python3 codex-instruct-vX.Y.Z.py --version. To inspect the current state, use --status. To see what would happen, use --dry-run. Only after reviewing the target directory, prompt source, and write plan do you add --yes. The quick start shows --codex-dir ~/.codex and --lang zh-CN. On Windows, replace python3 with python.
Rollback and recovery: restore, uninstall, reactivate
Undo is layered. --restore-hooks puts the hooks back, --uninstall shows a plan and --uninstall --yes carries it out, and --reactivate is available from v0.3.9. The README's rule for all of them is to look at the plan first and restore only after confirming.
Limitations and failure modes
The most obvious limitation is the hook isolation. If you have custom hooks that you rely on, they stay isolated until you run --restore-hooks. That could break workflows that depend on hooks for linting or security checks. Another limitation is the beta status of Windows fresh deployments, marked EXPLICIT_BETA in the README. The desktop build is unsigned, is not signed by SignPath Foundation, and will run into Gatekeeper or SmartScreen. The README requires Python 3.10+, so older Python versions are unsupported. If you need a project-scoped instruction import, this tool is the wrong fit because it operates globally.
Alternatives: claude-keysmith and manual editing
The same author maintains claude-keysmith for Claude Code. The README's table lists claude-keysmith for Claude Code, started from source, while codex-keysmith targets Codex and starts from a stable release script. If you only need to edit Codex's config.toml once, manual editing is simpler, but you lose the preview, backup, and rollback features. The README also lists grok-keysmith and zcode-keysmith for other tools, but they are not direct substitutes for Codex. Choose codex-keysmith only if you accept the global scope and want the transaction safety.
Maintenance and license implications
The project is MIT licensed, which allows free use and modification, but the README includes no legal advice. There is no pip package, so updates come as release assets; you must manually download and verify each new version. The latest release is v0.6.0, and the README's quick start uses a vX.Y.Z placeholder that you replace with the latest stable tag from the Releases page. The tool does not collect or upload data during normal operation, but the README notes that the unsigned desktop builds are not signed by SignPath Foundation and points to the release notes for physical-device acceptance, which matters if you require verified binaries.
Editorial conclusion
Adopt codex-keysmith if you manage Codex globally and need a reversible, preview-first way to install an instruction file and isolate hooks. Skip it if you prefer project-level instruction imports (Claude Code style) or if you run Windows in production, since fresh deployments there are explicitly beta. Before deploying, verify the checksum of the release asset, run --status and --dry-run against your actual codex-dir, and read docs/reference.md for the details.
Frequently asked questions
What does codex-keysmith actually install?
It deploys instruction files into a local Codex configuration directory. It does not modify the Codex software itself and does not read accounts or keys, and by default it installs a single draft.
How do I undo a codex-keysmith installation?
Three separate switches exist: `--restore-hooks` to put hooks back, `--uninstall` to remove the deployment, and `--reactivate`, available since v0.3.9. Each shows a plan first and only acts after you confirm, or immediately when you add `--yes`.
Does codex-keysmith work on Windows?
Fresh deployment on Windows is described as a test channel, while macOS and Linux are the primary targets. You need Python 3.10 or newer, and on Windows you replace `python3` with `python`. Unsigned desktop builds also trigger Gatekeeper and SmartScreen.
Official sources
Was this useful?