---
name: permissions-cleaner
description: >
  Audit and optimize Claude Code permissions across all config files.
  PROACTIVELY use when: (1) user says "clean permissions", "audit permissions",
  "optimize settings", (2) permission denied errors occur frequently,
  (3) after adding many one-off permissions, (4) periodically for maintenance.
  Analyzes global, project, and local settings for duplicates, consolidation
  opportunities, and dangerous permissions. Auto-applies safe changes.
allowed-tools: Read, Edit, Write, Bash, Glob, Grep
---

# Permissions Cleaner

Audit and optimize Claude Code permissions across all three config files.

## Quick Start

1. Read all three permission files
2. Analyze for duplicates, consolidation opportunities, and dangerous permissions
3. Auto-apply safe changes (deduplication, generalization)
4. Output warnings for dangerous permissions (never auto-remove)
5. Commit/push or dotsync as appropriate

## Config Files

| File | Location | Tracked | Purpose |
|------|----------|---------|---------|
| Global | `~/.dotfiles/claude/settings.json` | Yes (dotfiles) | All projects |
| Project | `.claude/settings.json` | Yes (git) | This project |
| Local | `.claude/settings.local.json` | No | Local dev only |

## Audit Scope

Full configuration audit including:
- `permissions.allow` - Allowed operations
- `permissions.ask` - Operations requiring confirmation
- `enabledPlugins` - Plugin configuration
- `mcpServers` - MCP server definitions
- Other settings (statusLine, etc.)

## Analysis Workflow

### Step 1: Load All Files

```bash
# Read global
cat ~/.dotfiles/claude/settings.json

# Read project
cat .claude/settings.json

# Read local (if exists)
cat .claude/settings.local.json 2>/dev/null
```

### Step 2: Identify Issues

**Duplicates**: Same permission in multiple files
- Example: `Bash(bun run:*)` in both global and local

**Overly Specific**: Could be generalized
- Example: `Bash(bun run:dev)` → `Bash(bun run:*)`
- Example: `WebFetch(domain:docs.example.com)` when global has `WebFetch(domain:*)`

**Wrong Location**: Should be in different file
- Project-specific paths → Keep in project
- Common patterns → Move to global

**Dangerous**: Security risks (warn only)
- See `references/dangerous-patterns.md`

### Step 3: Auto-Apply Safe Changes

**Safe to auto-apply**:
- Remove duplicates covered by global wildcards
- Generalize specific patterns to wildcards
- Move common patterns to global
- Clean stale entries for removed tools

**Never auto-apply**:
- Removing dangerous permissions
- Changing `.claude/settings.local.json` without asking
- Any change the user might disagree with

### Step 3.5: Maintain Audit Trail

**IMPORTANT**: When removing or approving dangerous permissions, update `references/dangerous-patterns.md`:

**For removals** - Add to "Removed Dangerous Patterns" table:
```markdown
| `Bash(sudo sed:*)` | 2026-01-12 | local | Can edit any system file as root |
```

**For approved exceptions** - Add to "Approved Exceptions" table:
```markdown
| `Bash(rm:*)` | 2026-01-12 | Simple file ops; rmrf preferred but rm allowed |
```

This creates a permanent record of security decisions for future audits.

### Step 4: Output Report

```markdown
## Permissions Audit Report

### ⚠️ WARNINGS (Dangerous Permissions)
- [file]: `permission` - Reason this is risky

### 🔄 Recommended Consolidations
- Move to global: `permission` (found in: project, local)
- Generalize: `Bash(bun run:dev)` → `Bash(bun run:*)`

### 🗑️ Duplicates to Remove
- [file]: `permission` - Already covered by global `pattern`

### ✅ Optimizations Applied
- Removed duplicate `X` from local (covered by global)
- Generalized `Y` to `Y*` in global
```

### Step 5: Post-Edit Actions

After making changes:

**If edited `.claude/settings.json`**:
```bash
git add .claude/settings.json
git commit -m "chore(claude): optimize permissions"
git push
```

**If edited global file**:
```bash
dotsync
```

## Permission Patterns

### Wildcards

| Pattern | Matches |
|---------|---------|
| `Bash(git *)` | All git commands |
| `Bash(bun:*)` | All bun commands |
| `WebFetch(domain:*)` | All domains |
| `mcp__*` | All MCP tool calls |

### Consolidation Rules

See `references/consolidation-rules.md` for detailed patterns.

## Dangerous Permissions

See `references/dangerous-patterns.md` for the full list.

Key patterns to warn about:
- `git push --force` / `git push -f`
- `git reset --hard`
- `rm -rf` without safeguards
- `Bash(*)` (unrestricted shell)
- `chmod 777`