A single-file Python CLI for paranoid Codex prompt deployment

What it does

codex-keysmith is a single-file Python CLI that deploys a Markdown instruction file into your Codex configuration directory and points config.toml at it. By default it runs in dry-run mode, showing exactly which files it would touch, what backups it would create, and whether it would isolate your active hooks.json. Only after you pass --yes does it actually write anything, and even then it backs up existing files before touching them.

The interesting bit

The tool treats prompt deployment as a transactional operation: it fingerprints files, detects concurrent modifications, and rolls back changes if anything goes wrong mid-flight. It also deliberately pauses your entire hooks.json during deployment—because the last thing you want is a hook continuing to inject context while you’re trying to redefine the ground rules.

Key highlights

• Zero dependencies beyond Python 3.8+; the entire tool is one script.
• Dry-run previews show every path, config delta, and hook isolation plan before any disk changes.
• Atomic renames and file fingerprints guard against concurrent edits; failed multi-directory deployments roll back in reverse order.
• Built-in hook isolation backs up hooks.json and disables it, with a separate --restore-hooks command to bring it back later.
• 71 pytest cases cover concurrency, interrupts, rollback, and prompt consistency.

Caveats

• Windows support exists but is not yet covered by CI; macOS and Linux are the validated targets.
• A hard kill (SIGKILL) or power loss can leave .keysmith-* transaction debris that blocks subsequent runs until manually cleared.
• It only touches the top-level model_instructions_file key in TOML, so profile-level isolation is out of scope.

Verdict

Worth a look if you manage Codex across multiple machines or directories and want a reversible, previewable way to standardize system prompts. Skip it if you just need a one-off copy-paste job and don’t care about hooks or backups.