claude-permissions-optimizer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Claude Permissions Optimizer

Claude权限优化器

Find safe Bash commands that are causing unnecessary permission prompts and auto-allow them in

settings.json

-- evidence-based, not prescriptive.

This skill identifies commands safe to auto-allow based on actual session history. It does not handle requests to allowlist specific dangerous commands. If the user asks to allow something destructive (e.g.,

rm -rf

git push --force

), explain that this skill optimizes for safe commands only, and that manual allowlist changes can be made directly in settings.json.

从会话历史中找出导致不必要权限提示的安全Bash命令，并自动将其加入

settings.json

的允许列表——基于实际使用证据，而非主观预设。

本技能会根据实际会话历史识别可自动允许的安全命令。它不处理将特定危险命令加入允许列表的请求。如果用户要求允许具有破坏性的命令（如

rm -rf

、

git push --force

），请说明本技能仅针对安全命令进行优化，如需添加危险命令，可直接在settings.json中手动修改允许列表。

Pre-check: Confirm environment

预检查：确认环境

Determine whether you are currently running inside Claude Code or a different coding agent (Codex, Gemini CLI, Cursor, etc.).

If running inside Claude Code: Proceed directly to Step 1.

If running in a different agent: Inform the user before proceeding:

"This skill analyzes Claude Code session history and writes to Claude Code's settings.json. You're currently in [agent name], but I can still optimize your Claude Code permissions from here -- the results will apply next time you use Claude Code."

Then proceed to Step 1 normally. The skill works from any environment as long as

~/.claude/

(or

$CLAUDE_CONFIG_DIR

) exists on the machine.

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

如果在Claude Code中运行： 直接进入步骤1。

如果在其他Agent中运行： 先告知用户，再继续操作：

“本技能会分析Claude Code的会话历史并写入Claude Code的settings.json。您当前正处于[Agent名称]中，但我仍可在此为您优化Claude Code的权限——优化结果将在您下次使用Claude Code时生效。”

之后正常进入步骤1。只要机器上存在

~/.claude/

（或

$CLAUDE_CONFIG_DIR

）目录，本技能可在任何环境下运行。

Step 1: Choose Analysis Scope

步骤1：选择分析范围

Ask the user how broadly to analyze using the platform's blocking question tool (

AskUserQuestion

in Claude Code,

request_user_input

in Codex,

ask_user

in Gemini). If no question tool is available, present the numbered options and wait for the user's reply.

All projects (Recommended) -- sessions across every project
This project only -- sessions for the current working directory
Custom -- user specifies constraints (time window, session count, etc.)

Default to All projects unless the user explicitly asks for a single project. More data produces better recommendations.

使用平台的阻塞式提问工具（Claude Code中为

AskUserQuestion

，Codex中为

request_user_input

，Gemini中为

ask_user

）询问用户分析范围。如果没有提问工具，则列出以下编号选项并等待用户回复。

所有项目（推荐）——分析所有项目的会话记录
仅当前项目——仅分析当前工作目录的会话记录
自定义——用户指定约束条件（时间范围、会话数量等）

默认选择所有项目，除非用户明确要求仅分析单个项目。数据越全面，推荐结果越准确。

Step 2: Run Extraction Script

步骤2：运行提取脚本

Run the bundled script. It handles everything: loads the current allowlist, scans recent session transcripts (most recent 500 sessions or last 30 days, whichever is more restrictive), filters already-covered commands, applies a min-count threshold (5+), normalizes into

Bash(pattern)

rules, and pre-classifies each as safe/review/dangerous.

All projects:

bash

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

This project only -- pass the project slug (absolute path with every non-alphanumeric char replaced by

, e.g.,

/Users/tmchow/Code/my-project

becomes

-Users-tmchow-Code-my-project

bash

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

Optional:

--days <N>

to limit to the last N days. Omit to analyze all available sessions.

The output JSON has:

green

: safe patterns to recommend

{ pattern, count, sessions, examples }

```
redExamples
```
: top 5 blocked dangerous patterns
```
{ pattern, reason, count }
```
(or empty)
```
yellowFootnote
```
: one-line summary of frequently-used commands that aren't safe to auto-allow (or null)

stats

totalExtracted

alreadyCovered

belowThreshold

patternsReturned

greenRawCount

, etc.

The model's job is to present the script's output, not re-classify.

If the script returns empty results, tell the user their allowlist is already well-optimized or they don't have enough session history yet -- suggest re-running after a few more working sessions.

运行内置脚本，该脚本会处理所有操作：加载当前允许列表、扫描近期会话记录（最近500条会话或过去30天，取范围更窄的那个）、过滤已覆盖的命令、应用最小次数阈值（5次及以上）、将命令规范化为

Bash(pattern)

规则，并预先将每个命令分类为安全/待审核/危险。

所有项目：

bash

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

仅当前项目——传入项目slug（将绝对路径中的所有非字母数字字符替换为

，例如

/Users/tmchow/Code/my-project

会变为

-Users-tmchow-Code-my-project

）：

bash

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

等

模型的任务是展示脚本的输出结果，而非重新分类。

如果脚本返回空结果，告知用户其允许列表已优化到位，或是会话历史数据不足——建议在进行几次工作会话后重新运行本技能。

Step 3: Present Results

步骤3：展示结果

Present in three parts. Keep the formatting clean and scannable.

分三部分展示结果，保持格式简洁易读。

Part 1: Analysis summary

第一部分：分析摘要

Show the work done using the script's

stats

. Reaffirm the scope. Keep it to 4-5 lines.

Example:

undefined

使用脚本返回的

stats

数据展示已完成的工作，确认分析范围。控制在4-5行以内。

示例：

undefined

Analysis (compound-engineering-plugin)

分析结果（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

undefined

扫描了该项目的24条会话记录。在这些会话中发现了312条唯一的Bash命令。

245条已被您现有的43条允许列表规则覆盖（占比79%）
61条使用次数少于5次（被过滤为噪音数据）
6条命令仍会频繁触发权限提示

undefined

Part 2: Recommendations

第二部分：推荐内容

Present

green

patterns as a numbered table. If

yellowFootnote

is not null, include it as a line after the table.

undefined

将

green

规则以编号表格的形式展示。如果

yellowFootnote

不为空，则在表格后添加该行内容。

undefined

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)


If `redExamples` is non-empty, show a compact "Blocked" table after the recommendations. This builds confidence that the classifier is doing its job. Show up to 3 examples.

序号	规则模式	依据
1	`Bash(bun test *)`	8个会话中使用23次
2	`Bash(bun run *)`	使用18次，覆盖开发/构建/ lint脚本
3	`Bash(node *)`	5个会话中使用12次

此外频繁使用的命令：bun install、mkdir（未被分类为可自动允许，但值得手动审核）


如果`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

undefined

规则模式	原因	使用次数
`rm *`	不可逆的文件删除	21
`eval *`	任意代码执行	14
`git reset --hard *`	销毁未提交的工作内容	5

undefined

Part 3: Bottom line

第三部分：核心结论

One sentence only. Frame the impact relative to current coverage using the script's stats. Nothing else -- no pattern names, no usage counts, no elaboration. The question tool UI that immediately follows will visually clip any trailing text, so this must fit on a single short line.

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

Compute the percentages from stats:

Before:
```
alreadyCovered / totalExtracted * 100
```

After:

(alreadyCovered + greenRawCount) / totalExtracted * 100

Use

greenRawCount

(the number of unique raw commands the green patterns cover), not

patternsReturned

(which is just the number of normalized patterns).

仅用一句话。结合脚本的统计数据，说明优化对当前权限覆盖范围的影响。无需额外内容——不要提及规则名称、使用次数或详细说明。后续的提问工具UI会截断多余文本，因此这句话必须简短且单行显示。

添加22条规则后，您的允许列表覆盖率将从65%提升至93%。

百分比计算方式：

优化前：
```
alreadyCovered / totalExtracted * 100
```

优化后：

(alreadyCovered + greenRawCount) / totalExtracted * 100

使用

greenRawCount

（绿色规则覆盖的唯一原始命令数量），而非

patternsReturned

（规范化规则的数量）。

Step 4: Get User Confirmation

步骤4：获取用户确认

The recommendations table is already displayed. Use the platform's blocking question tool to ask for the decision:

Apply all to user settings (
```
~/.claude/settings.json
```
)
Apply all to project settings (
```
.claude/settings.json
```
)
Skip

If the user wants to exclude specific items, they can reply in free text (e.g., "all except 3 and 7 to user settings"). The numbered table is already visible for reference -- no need to re-list items in the question tool.

推荐内容表格已展示，使用平台的阻塞式提问工具询问用户的决定：

应用到用户级设置 (
```
~/.claude/settings.json
```
)
应用到项目级设置 (
```
.claude/settings.json
```
)
跳过

如果用户希望排除特定规则，可通过自由文本回复（例如“除了第3和第7条，其余都应用到用户级设置”）。由于编号表格已展示，无需在提问工具中重新列出规则。

Step 5: Apply to Settings

步骤5：应用到设置

For each target settings file:

Read the current file (create
```
{ "permissions": { "allow": [] } }
```
if it doesn't exist)
Append new patterns to
```
permissions.allow
```
, avoiding duplicates
Sort the allow array alphabetically
Write back with 2-space indentation
Verify the write -- tell the user you're validating the JSON before running this command, e.g., "Verifying settings.json is valid JSON..." The command looks alarming without context:
bash
```
node -e "JSON.parse(require('fs').readFileSync('<path>','utf8'))"
```
If this fails, the file is invalid JSON. Immediately restore from the content read in step 1 and report the error. Do not continue to other files.

After successful verification:

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

was modified and is tracked by git, mention that committing it would benefit teammates.

针对每个目标设置文件，执行以下操作：

读取当前文件内容（如果文件不存在，则创建
```
{ "permissions": { "allow": [] } }
```
）
将新规则追加到
```
permissions.allow
```
数组中，避免重复
对allow数组按字母顺序排序
写入文件，使用2空格缩进
验证写入结果——在运行验证命令前告知用户，例如“正在验证settings.json是否为有效JSON...”。如果不添加上下文，验证命令可能会让用户感到不安：
bash
```
node -e "JSON.parse(require('fs').readFileSync('<path>','utf8'))"
```
如果验证失败，说明文件是无效JSON。立即从步骤1读取的内容恢复文件，并报告错误。不要继续处理其他文件。

验证成功后，告知用户：

已向~/.claude/settings.json应用N条规则
已向.claude/settings.json应用M条规则

这些命令将不再触发权限提示。

如果

.claude/settings.json

已被修改且受git追踪，可建议用户提交修改，以便团队成员受益。

Edge Cases

边缘情况

No project context (running outside a project): Only offer user-level settings as write target.
Settings file doesn't exist: Create it with
```
{ "permissions": { "allow": [] } }
```
. For
```
.claude/settings.json
```
, also create the
```
.claude/
```
directory if needed.
Deny rules: If a deny rule already blocks a command, warn rather than adding an allow rule (deny takes precedence in Claude Code).

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