codex-keysmith is a local-first Python command-line tool that installs, previews, versions, and removes instruction files for Codex, built for developers who want their Codex sessions to follow a controlled, reversible prompt configuration.

What it is

codex-keysmith is one member of the Keysmith family of instruction installers. It targets Codex specifically, and it works by writing an instruction draft into the local Codex configuration directory rather than by modifying the Codex software itself. It does not read accounts or credentials, and by default it installs a single draft. The project presents versioned deployment, ownership manifests, hook isolation, scenario evaluation, and recovery as its core concerns, and it is published under the MIT licence as a Python project with documentation in Simplified Chinese and English.

The problem it solves is the manual, untracked editing of Codex instruction configuration. Changing how Codex behaves normally means hand-editing files under the Codex config directory such as ~/.codex, with no preview, no record of what was changed, and no clean way to undo it. codex-keysmith replaces that workflow inside the codex-cli ecosystem: it first shows a plan covering the target directory, the prompt source, and the intended writes, and it writes only after explicit confirmation. Because the change applies to newly opened conversations under that Codex configuration, deployment becomes deliberate and reversible.

Key capabilities

• Preview-first deployment: --dry-run prints the target directory, prompt source, and write plan, and nothing is written until the run is confirmed with --yes.
• Versioned single-file release installers named like codex-instruct-vX.Y.Z.py, distributed from GitHub Releases with a matching SHA256SUMS file for checksum verification.
• Ownership manifests and hook isolation, so installed instructions and any hooks are tracked and kept separate.
• Scenario evaluation as part of the deployment flow.
• Recovery and removal commands: --restore-hooks, --uninstall, and --uninstall --yes, with --reactivate available from v0.3.9.
• Status inspection through --status, a selectable target directory through --codex-dir, and interface localisation through --lang zh-CN.

Who uses it and how

• Developers on macOS or Linux who run Codex locally and want reviewable instruction changes rather than ad-hoc edits.
• Users who delegate setup to an AI assistant by handing it docs/agent-install.md.
• Practitioners who standardise instruction deployment across several tools, using codex-keysmith for Codex, claude-keysmith for Claude Code, grok-keysmith for Grok Build, and zcode-keysmith for ZCode.
• Users who prefer an unsigned desktop build, available for Apple Silicon and Windows x64, instead of running the script directly.
• Windows users evaluating fresh deployment, which remains a test channel.

Getting started

Download the current stable single-file script from the latest release, where the public stable script includes codex-instruct-v0.5.1.py, verify it against SHA256SUMS, and run python3 codex-instruct-vX.Y.Z.py --codex-dir ~/.codex --dry-run --lang zh-CN before adding --yes to install. Python 3.10 or newer and a local Codex installation are required, and a git clone of the repository with the script renamed to codex-instruct.py is the source-based alternative.

How it compares

No paid products are named as replacements in the facts provided. Within the facts, codex-keysmith sits alongside its sibling installers, claude-keysmith, grok-keysmith, and zcode-keysmith, each targeting a different AI coding tool with its own installer rather than one tool covering all of them. Distribution differs across the family: codex-keysmith and grok-keysmith ship as stable release installers, while claude-keysmith and zcode-keysmith are built from source.

When to use it — and when not to

A self-hoster must already have Codex installed locally and needs Python 3.10 or newer; there is no hosted option, and the workflow is flag-driven rather than graphical. Fresh deployment on Windows is still a test channel, and the unsigned desktop builds trigger Gatekeeper on macOS or SmartScreen on Windows because they are not signed through the SignPath Foundation. Anyone who needs signed desktop binaries, a graphical installer, or support for a tool other than Codex should look at the sibling projects instead.

# 把 vX.Y.Z 换成 Releases 页的最新稳定 tag
base='https://github.com/Jia-Ethan/codex-keysmith/releases/download/vX.Y.Z'
curl --fail --location --remote-name "$base/codex-instruct-vX.Y.Z.py"
curl --fail --location --remote-name "$base/SHA256SUMS"
awk '$2 == "codex-instruct-vX.Y.Z.py"' SHA256SUMS | shasum -a 256 -c -

python3 codex-instruct-vX.Y.Z.py --version
python3 codex-instruct-vX.Y.Z.py --codex-dir ~/.codex --status --lang zh-CN
python3 codex-instruct-vX.Y.Z.py --codex-dir ~/.codex --dry-run --lang zh-CN
# 确认目标目录、提示词来源和写入计划后：
python3 codex-instruct-vX.Y.Z.py --codex-dir ~/.codex --yes --lang zh-CN

python3 codex-instruct-vX.Y.Z.py --codex-dir ~/.codex --restore-hooks --lang zh-CN
python3 codex-instruct-vX.Y.Z.py --codex-dir ~/.codex --uninstall --lang zh-CN
python3 codex-instruct-vX.Y.Z.py --codex-dir ~/.codex --uninstall --yes --lang zh-CN

python3 codex-instruct-vX.Y.Z.py --codex-dir ~/.codex --reactivate
python3 codex-instruct-vX.Y.Z.py --codex-dir ~/.codex --reactivate --yes --lang zh-CN