claude-keysmith: Plan-First Instruction Deployment for Claude Code

The problem is not writing instructions, it is undoing them

Claude Code reads instruction files from a project or a user location, and once a file is there it silently shapes every new conversation. The common failure is not that the file is wrong on day one. It is that nobody remembers which file was added, which scope it went into, or how to get back to the previous state. claude-keysmith treats that as the actual problem. Its README states the intent plainly: preview first, write after confirmation, verify, and be able to withdraw. The target user is someone already running Claude Code who wants a managed instruction payload rather than a hand-edited file. The README also says the tool does not modify the Claude Code program itself and does not read accounts or keys, which matters because it means the install is reversible at the file level rather than by reinstalling an application.

Plan, confirm, apply, withdraw: the four-state flow

The mechanism is a two-pass CLI. The first invocation prints a plan and writes nothing. The second invocation, with --yes appended, performs the write. The README's own four-step description is plan, install after confirmation, start a new conversation, and withdraw later using the same plan-then-confirm sequence. Two consequences follow from that design and both are stated in the README. First, the effect is not retroactive: it changes conversations opened after the install, and the README tells you to open a new session. Second, the uninstall path is symmetric with the install path, which is the part most instruction-file workflows get wrong. The README does not describe the on-disk format of the plan, the exact file path written under project scope, or whether a backup of a pre-existing instruction file is taken. Those are the details to check in docs/reference.md before trusting it on a repository where an instruction file already exists.

The install and uninstall commands, as given

The README ships a source-based workflow pinned to the release tag. Clone the tag shallowly, enter the directory, then run the installer twice. The first run shows the plan. The second run adds --yes. The same shape applies to removal. The README also points at docs/agent-install.md, which is written to be handed to an AI assistant so the assistant performs the install on your behalf, and at docs/reference.md for the full option list. Requirements are macOS, Windows or Linux with Python 3.8 or newer, and Claude Code already installed on the machine. Note what is absent: there is no pip install line and no package name in the README, so the supported entry point is the checked-out script. The project is MIT licensed, which permits modification and redistribution, but the README does not discuss what happens to the licence notice if you vendor the script into an internal repository. That is a question for your own legal review, not something the documentation answers.

The four-task comparison is the weakest evidence in the repository

The README includes a results graphic showing that on the same four tasks with the same model, the number of tasks producing a complete deliverable moved from one to three. That is the project's own claim about its own instruction payload, presented as an image with no methodology section in the README. Four tasks is a small sample, the tasks are not listed, and there is no statement about how many runs were performed or how the outputs were scored. Treat it as an illustration of the intended effect rather than as a measurement you can plan around. If you need to know whether a specific instruction payload improves your own work, you have to run your own comparison, and claude-keysmith gives you a clean way to do that because the payload can be removed again.

The desktop beta is unsigned, and the README says so

There is a Tauri-based desktop application for macOS and Windows, listed in the repository topics and mentioned in the README as an unsigned beta. The README's own selection table is the clearest signal about maturity: Codex and Grok Build users are pointed at a stable installer, while Claude Code and ZCode users are pointed at the source. For this project specifically, the desktop build is the secondary path, and unsigned means the operating system will warn on first launch. If your environment blocks unsigned binaries by policy, the desktop app is not an option and the CLI is the only route. The README does not state whether the desktop app and the CLI share the same plan format or whether one can undo the other's writes, which is worth confirming before mixing them on one machine.

Where a single-payload installer is the wrong tool

claude-keysmith manages one instruction payload for one target. If your team needs different instructions per repository, per language, or per developer role, this tool does not express that; you would be running it repeatedly with different project directories and tracking the results yourself. It also does not compose. There is no documented merge step, so if a repository already carries a hand-written instruction file, the README does not say whether the install replaces it, appends to it, or refuses. That gap is the single most important thing to verify before running the installer on a real project. And because the effect only applies to newly opened conversations, anyone debugging a behaviour change in an existing session is looking at the wrong session. A plain committed instruction file in the repository has none of these constraints: it is versioned by git, reviewed in a pull request, and equally visible to every teammate. What it lacks is the plan-then-confirm step and the built-in removal, which is exactly what claude-keysmith adds.

Maintenance cost and what the version pin buys you

The README pins the clone to a release tag rather than the default branch, and the latest release listed is v7.2 from September 2026. Pinning means you get a reproducible script and you also get the maintenance obligation that comes with it: upgrades are a manual re-clone at a new tag, not a package manager command. The project is part of a family of four installers (codex-keysmith, claude-keysmith, grok-keysmith, zcode-keysmith), each targeting a different AI coding tool, so the shared conventions are worth knowing if you use more than one. The MIT licence places essentially no restriction on internal use, modification, or redistribution. The documentation does not address whether the desktop beta is covered by the same licence terms as the CLI, and it does not describe a supported upgrade path between major versions. Both are things to settle by reading the release notes rather than assuming.

Editorial conclusion

Adopt claude-keysmith if you already run Claude Code and want one instruction file that can be inspected before it lands and removed afterwards; the two-step install and uninstall commands are the entire contract. Do not adopt it if you need a signed desktop binary, a stable package on PyPI, or per-user instruction management, because the README routes Claude Code users to a source checkout and labels the desktop build unsigned. Before installing, read docs/reference.md for what --scope project actually writes and where, and run the install once without --yes to see the plan on your own machine.

Official sources

1. Jia-Ethan/claude-keysmith on GitHub
2. License: MIT
3. Project website
4. README
5. Releases