grok-keysmith: preview-first instruction deployment for Grok Build
Preview-first Grok Build instruction deployment with compat and hook isolation, durable recovery, and layered uninstall.
At a glance
- What is it?
- grok-keysmith is a Python CLI that writes a versioned instruction file into a local Grok Build setup, showing a dry-run plan before anything changes and offering a layered uninstall. The trade-off is that it is a single-tool installer with a thin documented surface.
- Who is it for?
- Adopt grok-keysmith if you already use Grok Build locally and want an instruction file you can inspect before writing and remove afterwards without hand-editing config. Do not adopt it if you need a tool that manages instructions across several assistants at once, or if you are not on Grok Build at all, because the README scopes it to that one client.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 7 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 17, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What grok-keysmith solves, and for whom
Grok Build reads an instruction file that shapes how new conversations behave. Putting that file in place by hand means editing configuration you did not write, with no easy way back. grok-keysmith is a Python CLI that does the write for you, but only after it has shown you the plan. The README states the default is preview only: "默认只给你看计划，加上确认才会写入", meaning nothing is written until you pass the confirmation flag.
The audience is narrow by design. The README says the machine must already have Grok Build in use, and the tool targets Grok Build specifically. It does not touch the Grok application itself and, per the README, does not read accounts or keys. If you are a developer who wants a repeatable way to drop a prompt or instruction set into a local AI coding client and get it back out again, that is the exact use case. If you want a general configuration manager for many tools, this is not it.
The preview, confirm, write, revert cycle
The mechanism is a four-step cycle the README lays out: preview, confirm, start a new conversation, revert. The first step is a dry run. The README states that before confirmation nothing is written to disk, so the dry run is a plan rather than a partial install. Confirmation then hands the instruction to the local Grok Build installation while leaving the application untouched.
The effect is deferred. The README warns in an important callout that the install changes Grok conversations opened afterwards, not the one you are in, and asks you to open a new session once the install finishes. That is a real constraint on how you verify the change: an existing session will not show it.
Revert follows the same shape. The README describes uninstall as showing a plan first and restoring the previous state after confirmation. The repository description calls this a layered uninstall, and the description also mentions compat and hook isolation and durable recovery. The README itself does not expand on those terms, so treat them as claims to check in docs/reference.md rather than documented behaviour.
Installing grok-keysmith from the release archive
The README recommends the stable zip archive and notes that Grok Build should already be in use on the machine. The commands below come straight from that section. The first block downloads the v0.6.1 archive, unpacks it and moves into the extracted directory.
curl -LO https://github.com/Jia-Ethan/grok-keysmith/releases/download/v0.6.1/grok-keysmith-v0.6.1.zip
unzip grok-keysmith-v0.6.1.zip
cd grok-keysmith-v0.6.1From inside that directory, run the dry run first. The README's own sequence puts the preview before the confirmed install, and the output is a plan you are expected to read rather than a completed write.
python3 grok-keysmith.py --dry-run
python3 grok-keysmith.py --yesThe README states that after the confirmed run you should open a new Grok session for the instruction to take effect. It also points to docs/agent-install.md, which you can hand to an AI assistant to perform the install for you, and to docs/reference.md for the details. The project requires Python 3.8 or later, and the README lists macOS, Windows and Linux as supported.
Removing it again with --uninstall
Uninstall mirrors the install. The README gives two commands: one that shows the plan and one that confirms it.
python3 grok-keysmith.py --uninstall
python3 grok-keysmith.py --uninstall --yesThe README's wording is that the tool shows the plan first and restores the previous state after confirmation. What it does not document is the granularity of that restore. The repository description calls the uninstall layered, which suggests removal happens in stages rather than one delete, but the README does not enumerate those layers or say which files survive. If you care about what remains on disk after a revert, that is the question to answer from docs/reference.md before you install, not after.
Where grok-keysmith is the wrong tool
The README's own comparison table is the clearest limitation. It lists four separate installers, one per client: codex-keysmith for Codex, claude-keysmith for Claude Code, grok-keysmith for Grok Build, and zcode-keysmith for ZCode. Each tool ships its own installer. There is no single command that manages instructions across all four, so a team running more than one of these assistants ends up installing and reverting each one separately.
The second limitation is verification. Because the effect only appears in conversations opened after the install, you cannot confirm the instruction is active inside the session where you ran the command. Anyone expecting immediate feedback will be misled by the absence of a change.
The third is documentation depth. The README covers the happy path well and points to docs/reference.md, docs/agent-install.md and SECURITY.md, but the top-level README does not describe the file layout the tool writes, the compat and hook isolation behaviour named in the repository description, or what durable recovery restores. The README is silent on rollback beyond the uninstall command. If your environment has strict change-control requirements, that silence is a blocker until you read the linked docs.
How it differs from writing the instruction file yourself
The obvious alternative is to place the instruction file by hand, or to use whatever configuration mechanism Grok Build itself exposes. The difference in approach is the plan step. A manual edit is immediate and silent: you write the file and the next conversation picks it up, with no record of what changed and no built-in way back. grok-keysmith inverts that order by making the dry run the default and requiring an explicit confirmation flag before any write happens.
That ordering has a cost. You pay an extra command per install and per revert, and you have to read the plan to get value from it. The benefit is that the state before and after is something the tool tracks rather than something you reconstruct from memory or version control. For a one-off experiment on a throwaway machine, hand-editing is faster. For a machine you use daily and want to return to a known state, the extra step is the point.
Maintenance, platform support and licence
The repository is not archived, and the last push was on 2026-09-11. Two releases landed around that period: v0.6.1 on 2026-09-10 and v0.6.0 on 2026-09-10, and pyproject.toml declares version 0.6.1 with requires-python set to >=3.8. The release cadence is recent and the version numbers are close together, which is consistent with active work on a young project rather than a settled one. Expect the documented surface to move.
The upgrade path is not spelled out. The README gives a download-and-unzip flow for the release archive and a separate uninstall command, but it does not describe upgrading from one version to the next, nor whether an upgrade overwrites an existing instruction file. Because the tool writes into a Grok Build installation, that gap matters more than it would for a standalone utility. The README does not document rollback beyond --uninstall.
The project is MIT licensed, which permits commercial and private use with the usual attribution and warranty terms. The README also references a SECURITY.md and states that the tool does not read accounts or keys. For an organisation that needs legal sign-off, the licence text in LICENSE is the authority, not this summary.
Editorial conclusion
Adopt grok-keysmith if you already use Grok Build locally and want an instruction file you can inspect before writing and remove afterwards without hand-editing config. Do not adopt it if you need a tool that manages instructions across several assistants at once, or if you are not on Grok Build at all, because the README scopes it to that one client. Before running the confirmed install, run the dry-run and read docs/reference.md, since the README does not document where the instruction file lands or what --uninstall restores on each platform.
Frequently asked questions
Does grok-keysmith work on macOS?
Yes. The README lists macOS, Windows and Linux as supported environments, and requires Python 3.8 or later on the machine.
What does grok-keysmith actually change when I install it?
The README states it hands an instruction to the local Grok Build installation without modifying the Grok application itself, and that the instruction affects conversations opened after the install. It does not read accounts or keys.
How do I remove grok-keysmith after installing it?
Run python3 grok-keysmith.py --uninstall to see the plan, then python3 grok-keysmith.py --uninstall --yes to confirm. The README says the plan is shown first and the previous state is restored after confirmation.
Why do I see no change right after installing grok-keysmith?
The README's important callout says the install changes Grok conversations opened afterwards, and asks you to start a new session once the install completes. An existing conversation will not pick up the instruction.
Community notes