codex-keysmith: A Dry-Run-First Deployer for Codex Global Instructions

What codex-keysmith solves

Codex reads a global instruction file from config.toml's model_instructions_file. Editing that file by hand is easy but risky: a typo can change behavior across every new session, and there is no built-in way to revert. codex-keysmith addresses that by turning deployment into a three-step ritual: preview, confirm, write. The README is explicit that this is not a project-level switch; it changes global behavior under the given 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 writes a Markdown file (default gpt-unrestricted.md) into the Codex config directory, typically ~/.codex. It modifies only the top-level model_instructions_file in config.toml. Critically, it moves the entire hooks.json to hooks.json.disabled by default. That hook isolation is a deliberate design choice: if the new instruction set expects no hooks, or if hooks would interfere with the new setup, they are disabled wholesale. A manifest at .codex-keysmith-manifest.json records ownership of the layer, which uninstall uses. The README warns that this changes global behavior, not project scope, so the blast radius is wider than a typical dotfile manager.

Running it: commands and flags

Installation is not via pip. You download a single-file release asset, codex-instruct-v0.3.9.py, plus SHA256SUMS, and verify the checksum with shasum -a 256 -c. The README explicitly says not to pipe curl output into python. 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, but omitting --codex-dir processes all auto-discovered config directories. On Windows, replace python3 with python.

Rollback and recovery: restore, uninstall, reactivate

Undo is layered. --restore-hooks restores hooks.json from its disabled state, and the README notes it executes immediately without accepting --yes. --uninstall removes the latest layer only, not all historical layers. --reactivate, available from v0.3.9, repairs a missing top-level model_instructions_file when --status reports inactive-by-config. It does not re-run a full deployment. --recover handles only deploy/uninstall interrupted transactions. The README warns not to manually delete the journal, backup, or manifest. Recovery is not a durable journal; it rolls back catchable batch failures but cannot handle a hard kill. After a hard interrupt, you run --status first, then --reactivate --yes if there are no conflicts.

Limitations and failure modes

The most obvious limitation is the hook isolation: moving hooks.json to hooks.json.disabled is a blunt instrument. If you have custom hooks that you rely on, this tool will silently disable them unless you explicitly restore. 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 GUI is unsigned, not notarized, and may trigger Gatekeeper or SmartScreen. The CLI itself is also not signed by SignPath, and there is no pip install or auto-update. The README recommends Python 3.10 to 3.14, 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 key difference is the deployment surface: claude-keysmith writes a CLAUDE.md import block at project or user level, whereas codex-keysmith writes globally into ~/.codex. That makes claude-keysmith safer for per-project instruction sets, because it does not touch global hooks or config. 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.4.0, but the README's quick start references vX.Y.Z and the stable asset name v0.3.9. That mismatch is a maintenance cost: you need to check the Releases page for the actual tag. The README also warns not to use v0.1.0, implying early versions had issues. There is no auto-update, so you are responsible for tracking new releases. The tool does not collect or upload data during normal operation, but the README notes that current assets have not completed physical device acceptance and lack SignPath signing, 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 set model_instructions_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/hooks-transactions.md to understand the journal and recovery limits. Do not manually edit config.toml or delete journal, backup, or manifest files, as the tool's recovery depends on them.

Official sources

1. Official README
2. Project repository
3. Release notes