---
name: permission-tuner
description: Analyze permission logs and optimize settings.local.json to reduce permission prompts
allowed-tools: [Bash, Read, Write, Edit]
---

# Permission Tuner

Analyze the permission-requests.jsonl log to find frequently prompted permissions, then batch-update settings.local.json to reduce interruptions.

## When to Use

- "tune permissions", "optimize permissions", "reduce permission prompts"
- "analyze permission log", "what permissions am I being asked about"
- "update settings.local.json from logs"
- After a long session with many permission prompts
- Periodically to keep permissions current

## Prerequisites

The permission logging hooks must be active (PreToolUse logger + PermissionRequest handler). These log to `{project}/.claude/permission-requests.jsonl`.

## Instructions

### Step 1: Analyze the Log

Run the analyzer to see what's being prompted most often:

```bash
uv run python ~/.claude/skills/permission-tuner/scripts/analyze_permissions.py
```

Options:
- `--min-count 1` — show even single-occurrence prompts (default: 2)
- `--all` — include non-prompted tool uses (shows full usage, not just prompts)
- `--show-existing` — include permissions already in allow list
- `--format json` — machine-readable output for further processing

### Step 2: Present Findings to User

Show the table output. Highlight:
- **Safe** permissions (Read, Grep, Glob, Skill, Agent, mcp__*) — can approve freely
- **Review** permissions (Write, Edit, Bash git:*) — explain what they allow
- **Dangerous** permissions (Bash rm:*, sudo:*, chmod:*) — recommend keeping prompted

### Step 3: Get User Approval

Ask which permissions to add. Options:
- "Add all safe ones" — apply all safety=safe recommendations
- "Add these: 1, 3, 5" — pick by number from the table
- "Add all" — apply everything (warn if dangerous ones included)
- "Skip" — don't change anything

### Step 4: Apply Approved Permissions

For selected permissions, run:

```bash
uv run python ~/.claude/skills/permission-tuner/scripts/apply_permissions.py --permissions "Perm1" "Perm2" "Perm3"
```

Use `--dry-run` first if the user wants to preview.

### Step 5: Verify

Read the updated settings.local.json to confirm changes look correct.

### Step 6: Offer Log Rotation

If the log file is large (500+ entries), suggest:

> "The permission log has N entries. Want me to archive it and start fresh? This gives cleaner data for the next tuning session."

If yes, rename the log to `permission-requests.jsonl.bak` (ask first per destructive-commands rule).

## Important Notes

- **Never auto-approve dangerous permissions** — always flag rm, sudo, chmod, chown
- **Write/Edit permissions need path review** — ensure they're scoped to project directories, not system paths
- **Bash permissions are command-specific** — `Bash(git:*)` allows all git commands; `Bash(npm:*)` allows all npm commands. Review the command prefix.
- **The log is per-project** — each project's `.claude/` has its own log. The skill operates on the current project.
- **settings.local.json is per-project** — changes only affect the current project's permissions

## Safety Classification

| Classification | Examples | Default Action |
|---------------|----------|----------------|
| safe | Read, Grep, Glob, Skill, Agent, mcp__* | Auto-recommend |
| review | Write, Edit, Bash(git:*) | Explain scope, ask |
| dangerous | Bash(rm:*), Bash(sudo:*) | Warn, don't recommend |