claude-permissions-optimizer

Claude Permissions Optimizer

找出那些导致不必要权限提示的安全 Bash 命令，并将其自动加入 settings.json 的允许列表——基于证据，而非主观建议。

此技能会根据实际会话历史，识别可自动允许的安全命令。它不会处理将特定危险命令加入允许列表的请求。如果用户要求允许某些破坏性操作（例如 rm -rf、git push --force），请说明此技能只针对安全命令进行优化，并且可以直接在 settings.json 中手动修改允许列表。

预检查：确认环境

确定你当前是在 Claude Code 还是其他编码 Agent（Codex、Gemini CLI、Cursor 等）中运行。

如果在 Claude Code 中运行： 直接继续第 1 步。

如果在其他 Agent 中运行： 继续之前告知用户：

"此技能会分析 Claude Code 会话历史，并写入 Claude Code 的 settings.json。你当前使用的是 [agent name]，但我仍可以在此处优化你的 Claude Code 权限——下次使用 Claude Code 时即可应用这些结果。"

然后照常继续第 1 步。只要机器上存在 ~/.claude/（或 $CLAUDE_CONFIG_DIR），此技能就能在任何环境中运行。

第 1 步：选择分析范围

使用平台的阻塞式提问工具询问用户希望分析多大范围（Claude Code 中使用 AskUserQuestion，Codex 中使用 request_user_input，Gemini 中使用 ask_user）。如果没有可用的提问工具，请列出编号选项并等待用户回复。

1. 所有项目（推荐）——分析所有项目的会话
2. 仅此项目——分析当前工作目录的会话
3. 自定义——由用户指定限制条件（时间范围、会话数量等）

除非用户明确要求仅分析单个项目，否则默认选择 所有项目。数据越多，建议越准确。

第 2 步：运行提取脚本

运行随附脚本。脚本会处理所有工作：加载当前允许列表、扫描近期会话记录（最近 500 个会话或最近 30 天，以范围较小者为准）、筛除已有规则覆盖的命令、应用最低次数阈值（5 次及以上）、规范化为 Bash(pattern) 规则，并预先将每条规则分类为安全／需审核／危险。

所有项目：

node <skill-dir>/scripts/extract-commands.mjs

仅此项目——传入项目 slug（绝对路径，并将每个非字母数字字符替换为 -。例如，/Users/tmchow/Code/my-project 会变为 -Users-tmchow-Code-my-project）：

node <skill-dir>/scripts/extract-commands.mjs --project-slug <slug>

可选：使用 --days <N> 将范围限制为最近 N 天。不指定则分析所有可用会话。

输出 JSON 包含：

• green：建议加入允许列表的安全模式 { pattern, count, sessions, examples }
• redExamples：排名前 5 的受阻危险模式 { pattern, reason, count }（也可能为空）
• yellowFootnote：对常用但不适合自动加入允许列表的命令所做的一行摘要（也可能为 null）
• stats：totalExtracted、alreadyCovered、belowThreshold、patternsReturned、greenRawCount 等统计信息

模型的任务是呈现脚本输出，而不是重新分类。

如果脚本返回空结果，请告知用户其允许列表已得到良好优化，或者会话历史还不够丰富；建议再进行几次工作会话后重新运行。

第 3 步：呈现结果

分三部分呈现。保持格式清晰，便于浏览。

第 1 部分：分析摘要

使用脚本的 stats 展示已完成的工作。再次说明分析范围。控制在 4–5 行。

示例：

## Analysis (compound-engineering-plugin)

Scanned **24 sessions** for this project.
Found **312 unique Bash commands** across those sessions.

- **245** already covered by your 43 existing allowlist rules (79%)
- **61** used fewer than 5 times (filtered as noise)
- **6 commands** remain that regularly trigger permission prompts

第 2 部分：建议

将 green 模式以编号表格呈现。如果 yellowFootnote 不为 null，则在表格后添加该内容。

### Safe to auto-allow
| # | Pattern | Evidence |
|---|---------|----------|
| 1 | `Bash(bun test *)` | 23 uses across 8 sessions |
| 2 | `Bash(bun run *)` | 18 uses, covers dev/build/lint scripts |
| 3 | `Bash(node *)` | 12 uses across 5 sessions |

Also frequently used: bun install, mkdir (not classified as safe to auto-allow but may be worth reviewing)

如果 redExamples 不为空，则在建议之后添加一张精简的“已阻止”表格。这能让用户确信分类器正在发挥作用。最多展示 3 个示例。

### Blocked from recommendations
| Pattern | Reason | Uses |
|---------|--------|------|
| `rm *` | Irreversible file deletion | 21 |
| `eval *` | Arbitrary code execution | 14 |
| `git reset --hard *` | Destroys uncommitted work | 5 |

第 3 部分：结论

只能用一句话。 根据脚本统计数据，结合当前覆盖情况描述影响。除此之外不要写任何内容——不要提及模式名称、使用次数或展开说明。紧接着的提问工具界面会在视觉上截断任何多余文本，因此内容必须简短，且只占一行。

Adding 22 rules would bring your allowlist coverage from 65% to 93%.

根据统计数据计算百分比：

• 之前： alreadyCovered / totalExtracted * 100
• 之后： (alreadyCovered + greenRawCount) / totalExtracted * 100

使用 greenRawCount（绿色模式覆盖的唯一原始命令数量），不要使用 patternsReturned（它只是规范化模式的数量）。

第 4 步：征求用户确认

建议表格已经显示。使用平台的阻塞式提问工具征求用户决定：

1. 全部应用到用户设置（~/.claude/settings.json）
2. 全部应用到项目设置（.claude/settings.json）
3. 跳过

如果用户想排除特定项目，可以用自由文本回复（例如：“除了 3 和 7，其他全部应用到用户设置”）。编号表格已显示，可供参考——无需在提问工具中重新列出项目。

第 5 步：应用到设置

对于每个目标设置文件：

1. 读取当前文件（如果文件不存在，则创建 { "permissions": { "allow": [] } }）
2. 将新模式追加到 permissions.allow，避免重复
3. 按字母顺序对 allow 数组排序
4. 使用 2 个空格缩进写回
5. 验证写入结果——运行此命令前，告知用户你正在验证 JSON，例如：“正在验证 settings.json 是否为有效 JSON……”如果没有上下文，这条命令看起来会令人担忧：

   node -e "JSON.parse(require('fs').readFileSync('<path>','utf8'))"
   

   如果验证失败，说明文件不是有效 JSON。立即恢复为第 1 步读取的内容，并报告错误。不要继续处理其他文件。

验证成功后：

Applied N rules to ~/.claude/settings.json
Applied M rules to .claude/settings.json

These commands will no longer trigger permission prompts.

如果修改了 .claude/settings.json 且该文件由 git 跟踪，请提醒用户，提交该文件会让团队成员受益。

边缘情况

• 没有项目上下文（在项目外运行）：只提供用户级设置作为写入目标。
• 设置文件不存在：使用 { "permissions": { "allow": [] } } 创建。对于 .claude/settings.json，如有需要，也创建 .claude/ 目录。
• 拒绝规则：如果已有拒绝规则会阻止某个命令，请发出警告，而不是添加允许规则（在 Claude Code 中，拒绝规则优先级更高）。