claude-keysmith

Claude Code 指令文件部署：可管理的 CLAUDE.md import block，及可选的 user-scope runtime wrapper。

简体中文 · English · Reference · 智能体安装 / Agent install · License

简体中文

这是什么

claude-keysmith 是 Claude Code 的本地指令部署工具：它把一份 Markdown 指令保存到 keysmith 管理目录，并在 CLAUDE.md 或 CLAUDE.local.md 中插入可识别、可卸载的 import block。

可选的 --runtime 会额外对齐 settings.json 的 systemPrompt，并安装 managed shell wrapper，使每次 shell 调用自动带上 --system-prompt-file 与 --append-system-prompt-file：macOS / Linux 使用 ~/.zshrc 中的 claude()，Windows PowerShell 使用 profile 中的 function global:claude。

默认只预览；显式传入 --yes 才写入。写入前备份，卸载时只移除自己的 block 和文件。

[!WARNING] user scope 的 import block 会影响加载 ~/.claude/CLAUDE.md 的新会话；--runtime 还会影响通过 managed shell wrapper 启动的后续会话。先阅读 examples/claude-project-rules.md 和 examples/claude-append-prompt.md，运行 dry-run 确认路径与变更后，再使用 --yes。本工具不修改二进制、网络、MCP 或凭证，也不承诺覆盖 Claude Code、模型提供方或 API 网关的策略。

快速开始（macOS / Linux）

# 1. 先预览项目级部署；默认不写入
python3 claude-instruct.py install \
  --scope project \
  --project-dir /path/to/repo

# 2. 确认后才写入
python3 claude-instruct.py install \
  --scope project \
  --project-dir /path/to/repo \
  --name claude-project-rules \
  --yes

# 3. 检查状态
python3 claude-instruct.py status \
  --scope project \
  --project-dir /path/to/repo \
  --name claude-project-rules \
  --json

需要 user-scope runtime 时：

python3 claude-instruct.py install --scope user --runtime       # 先预览
python3 claude-instruct.py install --scope user --runtime --yes
source ~/.zshrc
python3 claude-instruct.py doctor --json

Windows PowerShell：

python .\claude-instruct.py install --scope user --runtime       # 先预览
python .\claude-instruct.py install --scope user --runtime --yes
. $PROFILE
python .\claude-instruct.py doctor --json

Windows 可用以下可选环境变量覆盖自动检测：CLAUDE_KEYSMITH_HOME、CLAUDE_KEYSMITH_SHELL、CLAUDE_KEYSMITH_SHELL_RC、CLAUDE_KEYSMITH_CLAUDE_BIN。

不要用 curl | python 直接执行；先下载或 clone 仓库、检查脚本与示例，再运行。

它会改哪些文件

完整所有权、settings 更新与恢复语义见 docs/reference.md。

撤销

# 项目级：先预览，再加 --yes
python3 claude-instruct.py uninstall \
  --scope project \
  --project-dir /path/to/repo \
  --name claude-project-rules

# user-scope runtime：移除 keysmith prompt 文件和 managed wrapper
python3 claude-instruct.py uninstall --scope user --runtime --yes

uninstall --runtime 不自动恢复 settings.json 的旧 systemPrompt，避免覆盖安装后由其他工具或用户写入的配置。需要恢复时，从安装前生成的 timestamp 备份显式执行：

python3 claude-instruct.py restore \
  --target ~/.claude/settings.json \
  --backup ~/.claude/settings.json.bak_YYYYMMDD_HHMMSS_pre_runtime \
  --yes

出问题了怎么办

兼容性与限制

• 推荐 Python 3.8+；runtime wrapper 支持 macOS / Linux 的 zsh 与 Windows 的 PowerShell。
• Windows 默认检测 PowerShell profile 与 npm 全局安装的 claude.cmd；可用 CLAUDE_KEYSMITH_* 环境变量覆盖路径。
• 只管理 claude-keysmith 自己插入的 HTML 注释 block，不覆盖用户其余 memory 内容。
• 不管理 Claude Code 二进制、运行中进程、网络、MCP、token、cookie、Base URL、hooks 或 permissions。
• 不验证某个既有会话是否重新加载指令；部署后启动新会话并做实际 smoke test。
• 备份不会自动删除；确认无需回滚后再手动清理。

参与贡献

python3 -m py_compile claude-instruct.py
python3 -m pytest tests

智能体安装流程见 docs/agent-install.md；文件所有权和完整运行时参考见 docs/reference.md。

友链 / Community

本项目接受 LINUX DO 社区佬友监督与反馈：LINUX DO

同系列项目 / Same series:

• codex-keysmith — Codex CLI versioned instruction deployment.
• claude-keysmith — Claude Code managed import-block installer.
• grok-keysmith — Grok Build AGENTS.md installer.
• zcode-keysmith — ZCode true system-role runtime entrypoint.
• role-keysmith — JD-matched Chinese resume rewriting skill.