Jia-Ethan/codex-keysmith

Versioned Codex instruction deployment with preview, ownership manifests, hook isolation, scenario evaluation, and recovery.

codex‑keysmith – Add reversible instruction hooks to your local Codex client

What it does

  • Provides a small Python installer that writes a prompt‑template (called a keysmith) into the configuration of a locally‑installed Codex desktop client.
  • The process is preview‑first, apply‑after‑confirmation and can be rolled back at any time.
  • Works without touching the Codex binary, reading your API keys, or sending any data to the internet.

How it works

  1. Dry‑run / preview – the script scans the target Codex directory, shows the exact files and hook code it would add, and prints a SHA‑256 checksum for verification.
  2. Apply – after you approve (--yes) the script writes the hook into the appropriate location and updates a small manifest so the new behaviour is active for new Codex conversations only.
  3. Re‑activate / uninstall – later you can restore the original files (--restore-hooks), completely uninstall the hook (--uninstall), or reactivate a previously saved state (--reactivate).

Supported platforms

  • macOS and Linux (officially supported)
  • Windows (beta channel, tested on x64)
  • Requires Python 3.10+.

Installation steps

# 1. Download the latest release script (replace X.Y.Z with the tag)
base="https://github.com/Jia-Ethan/codex-keysmith/releases/download/vX.Y.Z"
curl -L "$base/codex-instruct-vX.Y.Z.py" -o codex-instruct.py
curl -L "$base/SHA256SUMS" -o SHA256SUMS
# 2. Verify checksum
awk '$2 == "codex-instruct-vX.Y.Z.py"' SHA256SUMS | shasum -a 256 -c -
# 3. Preview what will be written
python3 codex-instruct.py --codex-dir ~/.codex --dry-run --lang zh-CN
# 4. Apply after you are happy
python3 codex-instruct.py --codex-dir ~/.codex --yes --lang zh-CN

Replace ~/.codex with the actual directory of your Codex installation.

Removing the hook

python3 codex-instruct.py --codex-dir ~/.codex --restore-hooks --lang zh-CN   # restore original files
python3 codex-instruct.py --codex-dir ~/.codex --uninstall --yes --lang zh-CN # delete the hook completely

Documentation & help

  • Detailed usage: docs/reference.md
  • How to let another AI assistant install it for you: docs/agent‑install.md
  • Security considerations: SECURITY.md
  • Community discussion: GitHub Discussions, LINUX DO forum.

License

  • MIT License – free to use, modify, and redistribute.

Why it matters codex-keysmith lets power users customise the behaviour of their local Codex coding assistant in a safe, reversible way. By injecting a prompt that runs before every new session, you can enforce coding standards, add project‑specific context, or experiment with new instruction sets without altering the core application.

Related

  • Project
    Jia-Ethan/grok-keysmith

    A command-line tool that allows users to inject and manage custom instructions for the Grok Build AI coding assistant, featuring a preview-before-apply workflow.

  • Project
    Jia-Ethan/claude-keysmith

    A tool for adding revocable custom instructions to Claude Code, allowing users to preview changes before applying them to new AI conversations.

  • Project
    leo-lilinxiao/codex-autoresearch

    Codex‑autoresearch is a Git‑backed Codex skill that runs an autonomous loop: propose a single code change, commit it, measure a numeric metric (e.g., test failures), keep the change if it improves the metric and passes optional guards, otherwise revert. It repeats until a user‑specified target is reached, storing an immutable event log and HTML report. Supports foreground or background execution, works with any measurable outcome, and enforces strict safety (all trials are real commits, failures abort with clear errors).

  • Project
    knoxgraeme/skillfish

    A CLI skill manager for AI coding agents that allows users to install, update, and sync portable prompt packages across tools like Claude Code, Cursor, and Copilot.