codex-keysmith
Versioned Codex instruction deployment with preview, ownership manifests, hook isolation, and layered uninstall.
简体中文 ·
English ·
Reference ·
Agent install ·
Security ·
License
## English
### What this is
`codex-keysmith` is a zero-dependency, single-file Python script that deploys an instruction Markdown file into your Codex configuration directory (`~/.codex`) so every new Codex session loads it. It previews by default and only writes on explicit confirmation; every deployment can be undone.
**This changes Codex's global behavior, not a per-project setting**: deployment edits `model_instructions_file` in `~/.codex/config.toml`, so it affects every new session under that configuration, and by default it pauses your entire existing `hooks.json` until you explicitly restore it. The bundled example prompt directs the model to drop refusal framing, treats reverse-shell/keygen/bypass requests as local fixtures, and covers adult and weapons/chemistry content. **This is a broad behavior change, not a safety boundary** — read [`examples/gpt-unrestricted.md`](examples/gpt-unrestricted.md) before using it, or supply your own file with `--file`.
> [!WARNING]
> Do not use the published `v0.1.0` on Windows; it has a known cleanup defect (see Compatibility below). v0.1.1 and later provide the native recovery backend; Windows fresh deployment remains beta.
### Quick start (macOS / Linux)
```bash
# 1. Download and verify (replace vX.Y.Z with the latest tag on the Releases page)
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"
shasum -a 256 -c SHA256SUMS
# 2. Look before you trust — confirm target directory, prompt source, and the planned write
python3 codex-instruct-vX.Y.Z.py --version
python3 codex-instruct-vX.Y.Z.py --codex-dir ~/.codex --status --lang en
python3 codex-instruct-vX.Y.Z.py --codex-dir ~/.codex --dry-run --lang en
# 3. Confirm only after reviewing the plan
python3 codex-instruct-vX.Y.Z.py --codex-dir ~/.codex --yes --lang en
```
Never install a formal release from a floating `main`, and never pipe `curl | python`. Save the file, verify it, then run it. **Close old tasks and start a new Codex session** after deployment — Codex loads configuration only at session start.
Omitting `--codex-dir` processes every auto-discovered directory; only do this for an intentional multi-directory deployment.
### Files it changes
| Path | What happens |
| --- | --- |
| `/gpt-unrestricted.md` (or custom `--name`) | Create, or back up and replace |
| `/config.toml` | Owns and edits only top-level `model_instructions_file`; external rewrites of other fields do not block status/uninstall and survive uninstall |
| `/hooks.json` | Isolated to `hooks.json.disabled` by default (backed up first) |
| `/.codex-keysmith-manifest.json` | Records what this deployment changed, for later uninstall |
Full field list, transaction directories, and edge cases: [`docs/reference.md`](docs/reference.md).
### Using CCSwitch profiles as an activation switch
When CCSwitch stores and replaces the complete Codex `config.toml` for each provider, two provider copies can hold separate Keysmith On / Off snapshots:
1. First inspect CCSwitch's Codex **Common Config Snippet**. It must not contain `model_instructions_file`, and the On / Off copies must not use “Apply Common Config” to share that field; otherwise the effective Off live config is merged back into On.
2. Select the copy that should be **On**, then deploy Keysmith. If only the prompt should switch and hooks must not become a global side effect, deploy with `--skip-hooks-isolation`.
3. Switch to an **Off** copy whose top-level config has no `model_instructions_file`, then verify with `--status`. On should report `Config activation: active` and Off should report `inactive-by-config`; if Off is still active, remove the field from both the provider config and Common Config Snippet. Off is not structural damage, but deploy and uninstall remain blocked; switch back to On before either write operation.
4. After uninstall, switch away from the cleaned On copy in CCSwitch normal mode, check for an “outgoing provider backfill failed” warning, then inspect that copy's stored config and confirm the field is gone. One completed switch alone does not prove that backfill succeeded.
This workflow was checked against CCSwitch v3.18.0 (`ff3bc242`) normal provider switching and backfill. In that version, proxy-takeover hot switching may also rebuild live config from a provider's effective configuration, but restore backups, Common Config merging, and proxy-field overrides are involved, so Keysmith does not treat it as a stable compatibility contract. Config switching affects only new sessions and never switches `hooks.json` / `hooks.json.disabled` with it.
### Undo
```bash
# Only restore hooks, leave instructions/config alone:
python3 codex-instruct.py --codex-dir ~/.codex --restore-hooks --lang en
# Fully undo this deployment (config, instruction, hooks together):
python3 codex-instruct.py --codex-dir ~/.codex --uninstall --lang en # preview first
python3 codex-instruct.py --codex-dir ~/.codex --uninstall --yes --lang en # confirm
```
Uninstall removes only the newest layer each run; repeat it to peel back earlier deployments. Long-lived config ownership covers only the top-level `model_instructions_file`: rewrites by CCSwitch or similar tools remain compatible while that field still references this layer's Markdown. Uninstall restores or removes only the pre-deployment field statement and preserves all other live content. A missing field is reported by read-only status as `inactive-by-config`, while deploy/uninstall still fail closed until an active profile restores the managed reference. A different target, target-field ambiguity, or unsupported statement structure remains a conflict.
### If something goes wrong
| Symptom | What to do |
| --- | --- |
| Hard interruption mid-deployment (`SIGKILL`, power loss) | Run `--status` first; if it reports `blocked`, preview `--recover`, then confirm with `--yes` |
| `--status` reports abnormal residue | Do not manually delete any `.codex-keysmith-transaction-*`, backup, or manifest; follow the `--recover` flow above, or see [`docs/hooks-transactions.md`](docs/hooks-transactions.md) |
| You want to clean up old backups | See the cleanup preconditions in [`docs/reference.md`](docs/reference.md); the tool never auto-deletes backups |
### Compatibility and limits
- Recommended Python 3.10–3.14; verified against `codex-cli 0.144.1`.
- macOS / Linux are the primary support range.
- **Windows**: the published `v0.1.0` has a known defect (`os.utime` failure followed by a second `PermissionError` that leaves a journal the old script can't recover). v0.1.1 and later include the rewritten Windows filesystem backend under `EXPLICIT_BETA` — usable, but not formally supported yet. If v0.1.0 left a journal on Windows, recover with the latest verified Release script in order: `--status` → `--recover` preview → `--recover --yes` → `--status`; never manually delete evidence.
- Single-file CLI, no `pip install` or auto-updater; backups and uninstall archives are not cleaned automatically.
- Full limits list, transaction guarantees, and maintainer verification: [`docs/reference.md`](docs/reference.md).
### Contributing and security reporting
Read [`CONTRIBUTING.md`](CONTRIBUTING.md) before submitting. Report vulnerabilities through the private channel in [`SECURITY.md`](SECURITY.md); do not paste credentials, complete configuration, or private paths into a public issue.
### Community
This project accepts monitoring and feedback from the LINUX DO community: [LINUX DO](https://linux.do)
Same series:
- [codex-keysmith](https://github.com/Jia-Ethan/codex-keysmith) - Codex CLI instruction-file deployment for local configuration.
- [claude-keysmith](https://github.com/Jia-Ethan/claude-keysmith) - Claude Code `CLAUDE.md` import-block installer for local instruction files.
- [grok-keysmith](https://github.com/Jia-Ethan/grok-keysmith) - Grok Build `AGENTS.md` installer with compat/hook isolation.
- [zcode-keysmith](https://github.com/Jia-Ethan/zcode-keysmith) - ZCode `AGENTS.md` installer for local instructions.
---
简体中文版: [`README.md`](README.md)。Agent install prompt: [`docs/agent-install.md`](docs/agent-install.md).