claude-permissions-audit

# Permissions Audit

Review and reorganize Claude Code permission settings so global settings are the
source of truth, project-local files stay minimal, and read vs write operations
have clear separation.

## When to Use

- Reviewing what tools and commands are pre-allowed
- Cleaning up accumulated ad-hoc permission entries
- After adding a new MCP server and deciding which operations to pre-allow
- Ensuring global vs project-local settings are properly split
- Periodic hygiene check on permission sprawl

## Phase 1: Discover All Settings Files

Scan for every settings file that contributes to the effective permission set.

**Locations to check:**
- `~/.claude/settings.json` — global settings (source of truth)
- `<project>/.claude/settings.json` — project shared settings (committed)
- `<project>/.claude/settings.local.json` — project local settings (gitignored)
- `~/.claude/.claude/settings.local.json` — home directory project local
- Any dotfiles-managed copy (e.g. `home/.claude/settings.json` in a dotfiles repo)

Read all of them in parallel. If a file doesn't exist, note it and move on.

## Phase 2: Audit

For each permission entry across all files, assess:

1. **Redundancy** — Is this entry already covered by a broader rule elsewhere?
   - Example: `Bash(gws calendar events:*)` is redundant when `Bash(gws:*)` exists globally
2. **Misplacement** — Is this general-purpose but stuck in a project-local file?
   - Example: `Bash(python3:*)` in project local when it's useful everywhere
3. **Inconsistent granularity** — Are similar tools allowed at different specificity levels?
   - Example: Global has `gh pr list`, `gh pr view` individually, but project local has `gh:*`
4. **Missing read/write distinction** — Are read-only and write operations mixed together?
5. **Stale entries** — One-time approvals that accumulated (e.g., a specific git command with hardcoded paths)

Present findings as a table with issues and proposed resolution for each.

## Phase 3: Propose Reorganization

Design the new layout following these principles:

### Global settings (source of truth)

Organize permissions into labeled sections by grouping related entries together.
Do NOT use JSON comments (// or /* */) — settings.json must be valid JSON.
Instead, rely on the ordering of entries to convey grouping. Within the allow
array, cluster related permissions together in this order:

**Section order (group entries in this sequence, no separators needed):**

```
filesystem reads            — cat, tree, grep, wc, file reads
<lang> inspection           — go doc, cargo check, linters (no side effects)
GitHub CLI reads            — gh pr list/view/diff, gh issue list (no mutations)
external tool reads         — calendar, slack CLI, other read CLIs
web reads                   — WebSearch, WebFetch with domain allowlist
MCP <service> reads         — list, get, describe, search operations
build / test / install      — go build, cargo test, pnpm install (local side effects)
skills                      — Skill(superpowers:*), etc.
```

### Project-local settings (minimal overrides)

Only keep entries that are genuinely project-specific:
- Broader tool access needed for a specific workflow (e.g., `Bash(gh:*)` for a repo that creates PRs frequently)
- Project-specific MCP tools not used elsewhere
- Temporary elevated access during active development

### Clarifying questions

Before applying, ask the user about edge cases. Common questions:

- **Scope of CLI tools**: Should `gh:*` (all subcommands) go global, or keep read-only globally with broader access per-project?
- **MCP write operations**: Which write operations (send message, create issue) should stay prompted vs pre-allowed?
- **Environment separation**: Should dev and prod data sources have the same read access, or should prod be more restrictive?
- **Dotfiles sync**: Does the user maintain a dotfiles copy that needs updating?

Adapt questions to what's actually ambiguous — don't ask about things that are obvious from context.

## Phase 4: Apply Changes

Once the user confirms the plan:

1. Write the updated global settings file
2. Write the trimmed project-local settings file
3. Update any dotfiles copies to stay in sync
4. Clear out entries from other local files that were absorbed into global

## Phase 5: Summary

Present a before/after comparison:

| File | Before | After |
|------|--------|-------|
| Global | N flat entries | M entries in K sections |
| Project local | X entries | Y entries (project-specific only) |

List what moved where, and what still requires prompting (write operations not pre-allowed).