Phx Permissions

Permission Analyzer

Scan recent session transcripts to find Bash commands you keep approving,

cross-reference with current settings.json, and recommend adding the missing ones.

Primary goal: Discover MISSING permissions from actual usage.

Secondary goal: Clean up redundant/garbage entries.

Usage

phx-permissions [--days=14] [--dry-run] — Scans session JSONL files, finds uncovered Bash commands, classifies risk, and recommends settings.json changes. Use --dry-run to preview without writing.

Arguments

$ARGUMENTS — --days=N (default: 14), --dry-run (preview only).

Iron Laws

• NEVER auto-allow RED — rm, sudo, kill, curl|sh, mix ecto.reset, git push --force, chmod 777
• Evidence-based only — Only recommend commands actually approved in sessions
• Show before writing — Present full diff, get explicit confirmation
• Preserve existing — Merge, never overwrite

Risk Classification

| Level | Examples | Action |

|-------|----------|--------|

| GREEN | ls, cat, grep, tail, which, mkdir, cd, mix test/compile/credo/format, git status/log/diff | Auto-recommend |

| YELLOW | git add/commit/push, mix ecto.migrate, mix deps.get, npm install, docker build/run, source, mise exec | Recommend with note |

| RED | rm -rf, sudo, kill, curl|sh,mix ecto.reset/drop,git push --force,git reset --hard | Never recommend |

Workflow

Step 1: Extract Bash Commands from Session JSONL Files

Run the extraction script from references/extraction-script.md.

This scans all project JSONL files from the last N days, checks each Bash command

against current settings.json patterns, and reports uncovered commands with counts.

IMPORTANT: Run this FIRST. Do NOT skip to settings cleanup.

Step 2: Classify and Recommend

For each uncovered command from Step 1 output:

• Classify as GREEN / YELLOW / RED per table above
• Generate permission pattern: normalize to Bash(base_command *) format

(use SPACE before *, NOT colon — :* is deprecated)

• mkdir -p (94x) → Bash(mkdir *)
• mise exec (39x) → Bash(mise *)
• tail -5 (20x) → Bash(tail *)
• Check for redundancy: skip if a broader existing pattern covers it
• Also scan for garbage in current settings: Bash(done), Bash(fi),

Bash(__NEW_LINE_*), partial heredocs, entries covered by broader patterns

• Fix deprecated :* patterns — replace any Bash(name:*) with Bash(name *)

(space before *). The :* suffix is deprecated and may not match reliably

Present a combined table:

## Permission Recommendations (last N days)

### ADD — Missing permissions (from session scan)
| Pattern to Add | Times Used | Risk | Example |
|...

### REMOVE — Redundant/garbage entries
| Entry | Reason |
|...

### RED — Require manual approval (not adding)
| Command | Count | Risk |
|...

Step 3: Interactive Triage (unless --dry-run)

Walk through findings interactively using AskUserQuestion. Present items

in batches by risk level, starting with GREEN (safest):

Batch 1 — GREEN items (read-only, tests, safe tools):

Use AskUserQuestion with options:

• "Add all GREEN" — approve entire batch
• "Pick individually" — show each one for yes/no
• "Skip GREEN" — move to YELLOW

Batch 2 — YELLOW items (write ops, need caution):

Always show individually — one AskUserQuestion per item with options:

• "Add" — include in settings
• "Skip" — keep requiring manual approval
• "Customize" — let user edit the pattern before adding

Batch 3 — REMOVE candidates (garbage/redundant):

Use AskUserQuestion with options:

• "Remove all" — clean up entire batch
• "Pick individually" — show each for yes/no
• "Keep all" — skip cleanup

Track approved items in a list. After triage, show final summary of

what will be added/removed and ask for confirmation.

Step 4: Apply

Merge approved additions into ~/.claude/settings.json under permissions.allow.

Remove approved garbage entries. Report final counts.

Workflow-artifact permissions (always check)

The plugin's workflow writes to .claude/plans/, .claude/solutions/, and

.claude/reviews/. If these aren't covered, phx-compound and review agents

get write-blocked mid-workflow. Recommend (GREEN):

Write(.claude/plans/), Write(.claude/solutions/), Write(.claude/reviews/**).

References

• references/risk-classification.md — Full classification rules
• references/settings-format.md — Permission pattern format

Related

Long mix output flooding context? phx-mix-compression installs rtk filters

that compress mix test/credo/dialyzer/compile output before it reaches the

transcript (5-15% token savings on mix-heavy sessions).