# claude-keysmith: managed Claude Code instruction deployment with a dry-run plan and a rollback path > claude-keysmith installs a persistent instruction file into Claude Code from source, showing a plan before it writes anything and offering an uninstall that restores the previous state. The desktop beta is unsigned, and the README documents source installation as the main route. **Jia-Ethan/claude-keysmith** — Managed Claude Code instruction deployment with safe CLI recovery and an unsigned macOS/Windows desktop beta. - Repository: https://github.com/Jia-Ethan/claude-keysmith - Website: https://github.com/Jia-Ethan/claude-keysmith/releases - Stars: 818 · Forks: 147 - Language: Python - License: MIT - Published: 2026-09-10 · Updated: 2026-09-10 · Language: en - Canonical page: https://hysenlabs.com/projects/jia-ethan-claude-keysmith ## The problem claude-keysmith addresses for Claude Code users Claude Code accepts instructions that shape how it behaves in a session. Keeping those instructions consistent across machines, projects and teammates is manual work: someone edits a file, someone else forgets, and the only way to undo a bad change is to remember what the file looked like before. claude-keysmith treats that instruction file as a deployable artifact. The README states the goal plainly: install an instruction into the local AI coding tool, preview it first, write it after confirmation, verify it, and be able to take it back out. It targets Claude Code specifically, and the README says it does not modify the Claude Code software itself and does not read accounts or keys. The intended audience is a developer who already has Claude Code installed on macOS, Windows or Linux and wants a repeatable way to put project rules in front of it. ## Plan, confirm, apply, revert: the four-step mechanism The workflow is deliberately staged. The README describes four steps: see the plan, confirm and install, open a new conversation, and remove it later with the same plan-first flow. Nothing is written before confirmation. That ordering is the whole design: the install and uninstall commands are the same shape, and the --yes flag is what turns a preview into an actual write. The README notes that the change applies to conversations opened after installation, so an existing session keeps its old behaviour. It also points to docs/agent-install.md, which is written so you can hand the installation task to an AI assistant you are already using. The repository layout backs this up: claude-instruct.py is the entry point, with docs/, examples/, gui/, tests/ and tools/ alongside it. The examples directory contains claude-append-prompt.md and claude-project-rules.md, which suggests the installed content is a prompt or rule document rather than arbitrary code. ## Installing claude-keysmith from source and running a first install The README says source installation is currently the main route, and Claude Code must already be installed on the machine. The commands below clone the v7.2 tag shallowly, enter the directory, and run the installer twice: once to see the plan, once with --yes to commit it. The first invocation should print a plan and write nothing; the second should apply it. ```bash git clone --branch v7.2 --depth 1 https://github.com/Jia-Ethan/claude-keysmith.git cd claude-keysmith python3 claude-instruct.py install --scope project --project-dir . python3 claude-instruct.py install --scope project --project-dir . --yes ``` After the write, open a new Claude Code session for the instruction to take effect. To undo it, run the uninstall pair, again previewing before confirming: ```bash python3 claude-instruct.py uninstall --scope project --project-dir . python3 claude-instruct.py uninstall --scope project --project-dir . --yes ``` The README shows only the project scope. It does not document what other scope values do, so treat --scope project as the documented path and check docs/reference.md before trying anything else. ## Where claude-keysmith is the wrong tool, and what the README leaves open The strongest limitation is stated by the project itself: the desktop application is unsigned. On macOS and Windows that means the operating system will treat it as an unidentified build, and there is no documented signing or notarisation step in the README. If your environment requires signed installers, the desktop beta is not a fit, and the source route is the only documented alternative. Second, the tool requires Python 3.8+ on the machine doing the install, which rules out locked-down workstations where developers cannot run arbitrary Python. Third, the README does not document rollback beyond the uninstall command: it does not say what happens if the target file changed between install and uninstall, and it does not describe a backup location. That is a real gap for anyone planning to run this across a team. Fourth, the effect is scoped to new conversations, so anyone expecting existing sessions to pick up the rules will be surprised. Finally, the README's own results graphic is a four-question comparison and should be read as a small demonstration, not as a general performance claim. ## claude-keysmith versus codex-keysmith and the rest of the family The most useful comparison is inside the project's own family. The README lists four installers: codex-keysmith for Codex, claude-keysmith for Claude Code, grok-keysmith for Grok Build and zcode-keysmith for ZCode, with the instruction to pick the one matching the tool you use. The difference is not in the mechanism, which the README describes identically across the family, but in the target and the distribution channel: the table marks codex-keysmith and grok-keysmith as starting from a stable installer package, while claude-keysmith and zcode-keysmith start from source. So the practical alternative to claude-keysmith is not a competing product with a different architecture; it is doing the same job by hand, editing the Claude Code instruction file directly and keeping your own copy to restore from. That approach has no preview step and no confirmation gate, which is exactly the property claude-keysmith adds. ## Licence and the cost of keeping claude-keysmith current claude-keysmith is MIT licensed, and the LICENSE file sits at the repository root. MIT is permissive: it allows use, modification and redistribution with the licence text retained, and it comes with no warranty. That matters here because the tool writes into your local development environment, so the absence of warranty is not a formality. On upgrade cost, the repository keeps a CHANGELOG.md, and the README pins the clone command to the v7.2 tag rather than the default branch, which means an installed copy does not move on its own. Upgrading is a deliberate act: fetch a newer tag and re-run the install. The last push to the repository was on 2026-09-10, and the v7.2 release is dated the same day, so the tag and the current state of the code line up. There is no documented automatic update mechanism in the README. ## Conclusion Adopt claude-keysmith if you already run Claude Code locally and want an instruction set that can be previewed, verified and removed without touching the Claude Code installation itself. Skip it if you need a signed desktop installer, or if your team cannot run Python 3.8+ on developer machines. Before rolling it out, run the install command without --yes to read the plan, then check docs/reference.md for the exact scope semantics, because the README only demonstrates --scope project and does not describe what other scopes write. ## FAQ ### Does claude-keysmith change the Claude Code application itself? No. The README states that it does not modify the Claude Code software and does not read accounts or keys; it deploys an instruction that Claude Code picks up in new conversations. ### Which platforms does claude-keysmith support? The README lists macOS, Windows and Linux, and requires Python 3.8 or later on the machine running the installer. ### How do I undo a claude-keysmith install? Run the uninstall command without --yes to see the plan, then run it again with --yes to restore the previous state, as shown in the README's uninstall example. ### Does the installed instruction apply to conversations I already have open? The README says the change affects conversations opened after installation and asks you to start a new session once the install completes. ## Sources - [Jia-Ethan/claude-keysmith on GitHub](https://github.com/Jia-Ethan/claude-keysmith) - [License: MIT](https://github.com/Jia-Ethan/claude-keysmith/blob/main/LICENSE) - [Project website](https://github.com/Jia-Ethan/claude-keysmith/releases) - [README](https://github.com/Jia-Ethan/claude-keysmith/blob/main/README.md) - [Releases](https://github.com/Jia-Ethan/claude-keysmith/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/jia-ethan-claude-keysmith