Configuring Permissions

STOP: Freshness Check Required

Before using this skill: Check

.state

last_evaluated

find ~/.claude/plugins -path "*/claude-code/skills/configuring-permissions/.state" 2>/dev/null | head -1

Full procedure: freshness-check.md

Overview

Claude Code permissions control which tools/skills can run without prompting. Core principle: prompt grants update memory immediately; manual edits require restart.

CRITICAL

Team vs Solo Project Detection

Before modifying project settings: Check if changes affect a team (

git shortlog -sne --all | head -10

Skill(*)

Full decision flow: team-detection.md

Restart Requirement

When manually editing settings.json, tell user:

Restart Claude Code for the new permission to take effect.

Skill Permission Naming

Common mistake: Using marketplace name instead of plugin name.

superpowers@superpowers-marketplace

Skill(superpowers:*)

Skill(superpowers-marketplace:*)

hookify@claude-plugins-official

Skill(hookify:*)

Skill(claude-plugins-official:*)

The format is

Skill(plugin-name:skill-name)

Skill(marketplace-name:skill-name)

To find the correct plugin name: Look at the part BEFORE the

@

MCP Permission Syntax

MCP permissions support three patterns (docs):

mcp__server

mcp__server__*

mcp__server__tool

Example:

{
  "permissions": {
    "allow": [
      "mcp__serena",
      "mcp__claude-in-chrome",
      "mcp__effect-docs"
    ]
  }
}

Fully qualified names (e.g.,

mcp__serena__find_symbol

Note: Issue #3107 (July 2025) claimed wildcards weren't supported, but current docs confirm both patterns are valid and equivalent.

Skill Permissions

Skill(*)

• ~/.claude/settings.json

  (user): buggy, sometimes ignored (#5140, #10833)

• .claude/settings.json

  (project): doesn't work at all

• .claude/settings.local.json

  (project local): works, but see team workaround below

For individuals: Use explicit patterns in user settings:

"Skill(plugin-name:*)"

Extract plugin names from

enabledPlugins

@

For teams — Option A (simple, no personal overrides): Commit

.claude/settings.local.json

For teams — Option B (recommended, allows personal overrides): Use a SessionStart hook to sync baseline permissions:

1. Create

   .claude/settings.local.json.example

   (committed) with baseline permissions
2. Keep

   .claude/settings.local.json

   gitignored
3. Add SessionStart hook to sync example → local:

#!/bin/bash
# .claude/scripts/sync-local-permissions.sh
EXAMPLE=".claude/settings.local.json.example"
LOCAL=".claude/settings.local.json"

[[ ! -f "$EXAMPLE" ]] && exit 0

if [[ ! -f "$LOCAL" ]]; then
  cp "$EXAMPLE" "$LOCAL"
  echo "Created $LOCAL from example. Restart CC for permissions to take effect."
  exit 0
fi

CURRENT=$(jq -S '.permissions.allow // [] | sort' "$LOCAL" 2>/dev/null || echo '[]')
BASELINE=$(jq -S '.permissions.allow // [] | sort' "$EXAMPLE" 2>/dev/null || echo '[]')
MERGED=$(jq -n --argjson a "$CURRENT" --argjson b "$BASELINE" '$a + $b | unique | sort')

if [[ "$CURRENT" != "$MERGED" ]]; then
  jq --argjson allow "$MERGED" '.permissions.allow = $allow' "$LOCAL" > "$LOCAL.tmp" && mv "$LOCAL.tmp" "$LOCAL"
  echo "Added baseline permissions. Restart CC for changes to take effect."
fi

Hook in

.claude/settings.json

{
  "hooks": {
    "SessionStart": [{ "hooks": [{ "type": "command", "command": ".claude/scripts/sync-local-permissions.sh" }] }]
  }
}

Benefits: team gets baseline permissions, individuals can add extras without conflicts.

Tracking: #10833 — when fixed, move to

settings.json

Permission Files

~/.claude/settings.json

.claude/settings.json

.claude/settings.local.json

Adding Permissions

Via Prompt (Recommended)

Select "Yes, and don't ask again" → adds to appropriate settings file, no restart needed.

Via Manual Edit

{
  "permissions": {
    "allow": ["Bash", "Skill(superpowers:*)"],
    "deny": []
  }
}

Team-Shared Permissions

digraph team_permissions {
    "Project permission needed" [shape=box];
    "settings.local.json committed?" [shape=diamond];
    "Works for user only" [shape=box];
    "Share with team?" [shape=diamond];
    "Add to settings.local.json" [shape=box];
    "Override gitignore + commit" [shape=box];

    "Project permission needed" -> "settings.local.json committed?";
    "settings.local.json committed?" -> "Add to settings.local.json" [label="yes"];
    "settings.local.json committed?" -> "Works for user only" [label="no"];
    "Works for user only" -> "Share with team?";
    "Share with team?" -> "Override gitignore + commit" [label="yes"];
    "Share with team?" -> "Add to settings.local.json" [label="no"];
    "Override gitignore + commit" -> "Add to settings.local.json";
}

Check:

git ls-files .claude/settings.local.json

To share with team, override gitignore:

.claude/
!.claude/settings.local.json

Why commit: Team members get permissions automatically; worktrees don't inherit uncommitted files.

Permission Patterns — Complete Reference

Tools Requiring Permissions

No permission required: Glob, Grep, Read, NotebookRead, Task, TodoWrite

Pattern Syntax

# TOOLS (bare = all uses)
Bash                           # All bash commands
Edit                           # All file edits
Write                          # All file writes
MultiEdit                      # All multi-edits
WebFetch                       # All web fetches
WebSearch                      # All web searches

# BASH (prefix matching, NOT regex)
Bash(npm run build)            # Exact command
Bash(npm run test:*)           # Commands starting with "npm run test:"
Bash(git *)                    # Commands starting with "git "

# FILE PATHS (gitignore-style globs)
Read(~/**)                     # Read files in home (recursive)
Read(/src/**)                  # Relative to settings file location
Read(//absolute/path/**)       # Absolute filesystem path (note: //)
Edit(*.md)                     # Edit markdown files
Write(.claude/**)              # Write to .claude directory

# SKILLS
Skill(plugin-name:*)           # All skills from a plugin
Skill(plugin-name:skill-name)  # Specific skill from plugin
Skill(local-skill-name)        # Local skill (no colon)

# MCP SERVERS
mcp__server                    # All tools from server
mcp__server__*                 # All tools (wildcard, equivalent)
mcp__server__tool              # Specific tool only

# WEB
WebFetch(domain:example.com)   # Specific domain only

Local vs Plugin Skills

~/.claude/skills/foo/

Skill(foo)

.claude/skills/bar/

Skill(bar)

hookify@marketplace

Skill(hookify:list)

Skill(hookify:*)

Key distinction: Local skills have NO colon. Plugin skills have

plugin-name:skill-name

Known Issues (Jan 2026)

Symlinked settings.json Broken (#3575, #764, #18160) — OPEN

Problem: CC doesn't properly handle symlinked

~/.claude/settings.json

1. Read failures — permissions not recognized from symlinked files
2. Write breakage — CC's atomic writes replace symlinks with regular files
3. Performance degradation — symlinked settings cause multi-second command delays

Impact: Dotfiles users (stow, chezmoi symlinks, custom scripts) can't sync settings.json normally.

Workaround: Don't symlink settings.json. Let CC own

~/.claude/settings.json

For dotfiles ergonomics, create a reverse convenience symlink (gitignored) from your dotfiles repo to the runtime file:

# In dotfiles repo (gitignored):
ln -s ~/.claude/settings.json dotfiles/claude/settings.json

This lets you edit from your dotfiles workspace while CC owns the actual file.

Alternative tools:

• chezmoi — generates files instead of symlinks
• claude-code-config-sync — NPM sync with conflict resolution

Path Prefix Gotcha (#6881) — OPEN

/path

/src/**

<settings-dir>/src/**

//path

//Users/me/code/**

~/path

~/.config/**

Common mistake:

/Users/me/...

//Users/me/...

Skill Permissions Broken (#5140, #10833) — OPEN

Skill(*)

• User settings: sometimes ignored, worktree bug
• Project

  settings.json

  : doesn't work at all
• Project

  settings.local.json

  : works but blocks personal overrides

Team workaround: Commit

settings.local.json

Skill allowed-tools Broken (#14956) — OPEN

Skills with

allowed-tools

allowedTools

Workaround: Add patterns to global allow list directly.

Plugin Enable/Disable Ignored (#13344) — OPEN

When plugins share a source directory, disabling one loads all skills anyway.

enabledPlugins

Impact: ~35-40k tokens wasted on unwanted skills.

User Settings Sometimes Ignored (#5140) — OPEN

~/.claude/settings.json

.claude/settings.local.json

Fixed Issues (Reference)

Programmatic Editing (Hooks/Scripts)

When scripts modify settings.json:

Safe JSON Modification

SETTINGS_FILE="$HOME/.claude/settings.json"
PERMISSION="Skill(hookify:*)"

# Check if already present (avoid duplicates)
if ! jq -e --arg p "$PERMISSION" '.permissions.allow | index($p)' "$SETTINGS_FILE" >/dev/null 2>&1; then
  # Atomic write: tmp file + mv
  jq --arg p "$PERMISSION" '.permissions.allow += [$p]' "$SETTINGS_FILE" > "$SETTINGS_FILE.tmp" \
    && mv "$SETTINGS_FILE.tmp" "$SETTINGS_FILE"
fi

Critical Rules

1. Always use jq — Never sed/awk on JSON
2. Atomic writes — Write to

   .tmp

   , then

   mv

3. Check before adding — Use

   jq -e ... | index($p)

   to avoid duplicates
4. Validate result —

   jq empty "$SETTINGS_FILE"

   to verify valid JSON
5. Remember restart requirement — Script changes don't take effect until CC restarts

Lock File (Optional, for parallel safety)

LOCK_FILE="$HOME/.claude/settings.json.lock"
exec 200>"$LOCK_FILE"
flock -n 200 || { echo "Settings locked"; exit 1; }
# ... do work ...
flock -u 200

Notes

• *

  matches any characters;

  **

  matches directory depth
• Deny rules take precedence over allow
• Project settings override user settings