Most config helpers treat the write as the job. codex-keysmith treats it as something a person will want to reverse six weeks later, after they have forgotten what they installed and why their agent is behaving oddly. That assumption shapes the entire CLI: check status, preview the plan, then write, and keep a file on disk whose only purpose is to make the uninstall possible.
The tool itself does something simple. It deploys one Markdown file into a Codex configuration directory, usually ~/.codex, so that later sessions load it. The README opens with a warning instead of a pitch, and the warning is the right call. This changes global behavior for that Codex config. It is not a project-level switch.
The write is small and the blast radius is written down
Four paths change. <codex-dir>/gpt-unrestricted.md, or whatever you pass to --name, is either created or backed up and replaced. config.toml gets exactly one edit, the top-level model_instructions_file key. hooks.json is moved aside wholesale to hooks.json.disabled. Finally, .codex-keysmith-manifest.json records what this layer owns.
That last file is the one that makes the rest work. Uninstall reverses a single layer per run, newest first, which is only possible because each deployment wrote down its claim. Scenario deployments land somewhere else entirely, under <target>/.codex-keysmith/, and leave the instruction-layer files untouched.
The hook isolation deserves a pause. Disabling all of hooks.json by default is a heavy move on a shared config directory, and the tool acknowledges that by giving --restore-hooks different ergonomics from everything else. It runs immediately and refuses --yes. Deploying and uninstalling want a preview and a confirmation flag. Putting your hooks back does not.
Failure states get their own vocabulary
inactive-by-config is a named status, meaning the instruction file is still sitting there but config.toml no longer points at it. The prescribed fix is --reactivate, available from v0.3.9, which restores only the missing top-level key. The README explicitly tells you not to hand-edit config.toml and not to rerun a full deployment just to put one field back.
Then it does something I rarely see in a tool of this size: it publishes where the guarantees stop. --reactivate rolls back batch failures it can catch, but it creates no durable journal. After a hard interrupt you run --status first, and if nothing conflicts you rerun --reactivate --yes to finish the remaining directories. --recover handles interrupted deploy and uninstall transactions, and nothing else. Do not delete the journal, the backups, or the manifest by hand.
The batch language matters because omitting --codex-dir makes the tool process every configuration directory it auto-discovers. One careless invocation reaches further than one machine's obvious ~/.codex.
A second channel that ships broken code on purpose
The instruction channel is what most people will use. The environment channel is --scaffold, which writes deliberately incomplete fixture workspaces into ~/.codex-fixture-workspace/<pack> and does not modify ~/.codex at all. You list packs with --scaffold-list, preview with --dry-run, and commit with --yes, the same rhythm as the main path. The two channels can stack, and neither writes into the other's directory. If you are running the standalone single-file script without fixture_packs/ next to it, scaffolding prompts you to grab the release bundle or point at --pack-dir.
Distribution reflects the same caution
The recommended install is manual and slightly annoying, which is the point. Download the single-file codex-instruct-v*.py and SHA256SUMS from the latest stable release, verify the hash, then run it. The README states the anti-pattern outright: do not pipe curl into python. There is no pip install and no auto-update.
The rest of the limits are stated without hedging. macOS and Linux are the primary CLI targets, and a fresh Windows deployment is marked EXPLICIT_BETA. The Desktop build is unsigned and unnotarized, ships only for Apple Silicon and Windows x64, and may trip Gatekeeper or SmartScreen. Python 3.10 through 3.14 is the recommended range. The published v0.1.0 should not be used.
The same shape appears across the sibling projects for Claude Code, Grok Build, and ZCode, each aimed at a different tool's config surface. What carries over is not the prompt being deployed. It is the accounting around it.
GitHub: https://github.com/Jia-Ethan/codex-keysmith
Curated by Agent Palisade — practical AI for small and mid-sized businesses.
Top comments (0)