Claude Code Permissions Management

Guide for configuring permissions, sandboxing, and tool access in Claude Code.

Overview

Claude Code uses a tiered permission system to balance functionality and security. Permissions control what actions Claude can perform without explicit approval.

Permission Tiers

Read-Only Operations (No Approval Required)

These operations are automatically allowed:

• FileReadTool: Reading file contents
• LSTool: Listing files and directories
• GrepTool: Searching text within files
• GlobTool: Finding files matching patterns
• NotebookReadTool: Reading Jupyter notebook content

Bash Commands (Requires Approval)

BashTool execution requires user approval. Users can:

• Approve individual commands
• Choose "Always allow" for specific commands in a project directory
• Configure persistent permissions in settings.json

File Modifications (Requires Approval)

These operations require session-based approval:

• FileEditTool: Making partial edits to files
• FileWriteTool: Creating or overwriting files
• NotebookEditTool: Modifying cells in Jupyter notebooks

Available Tools

Claude Code provides these tools:

• AgentTool: Runs sub-agents for multi-step tasks
• BashTool: Executes shell commands
• GlobTool: Finds files matching patterns
• GrepTool: Searches text within files
• LSTool: Lists files and directories
• FileReadTool: Reads file contents
• FileEditTool: Makes partial edits to files
• FileWriteTool: Creates or overwrites files
• NotebookReadTool: Reads Jupyter notebook content
• NotebookEditTool: Modifies cells in Jupyter notebooks

Managing Permissions

Method 1: /permissions Command

Use the /permissions command to access the interactive UI for managing permissions:

• Allow: Grant Claude Code permission to use specified tools without further approval
• Ask: Prompt for confirmation each time a tool is used
• Deny: Prevent the use of specified tools entirely

Method 2: settings.json Configuration

Configure persistent permissions in .claude/settings.json or ~/.claude.json:

{
  "permissions": {
    "allow": [
      "Read",
      "Write",
      "Edit",
      "Bash(git status)",
      "Bash(git commit -m:*)"
    ],
    "deny": ["Read(.env*)", "Bash(rm -rf /)", "Bash(sudo:*)"],
    "ask": ["Bash(git push --force:*)", "Bash(docker run:*)"]
  }
}

Method 3: /allowed-tools Command

Use CLI to add or remove tools from allowlist:

• Add: /allowed-tools +Edit
• Remove: /allowed-tools -Bash
• Pattern: /allowed-tools +Bash(git commit:*)

Method 4: Session Flags

Use --allowedTools flag for session-specific permissions (not persistent).

Permission Patterns

Tool Patterns

• Simple tool: "Read", "Write", "Edit", "Bash"
• Specific command: "Bash(git status)"
• Command pattern: "Bash(git commit:*)" (matches all git commit commands)
• File pattern: "Read(.env*)" (matches .env files)
• Directory pattern: "Read(./secrets/**)" (matches files in secrets directory)

Wildcard Patterns

• * matches any string
• ** matches directories recursively
• Pattern matching is case-sensitive

Skill and SlashCommand Patterns

• All slash commands: "SlashCommand(*)"
• Specific main skill: "Skill(typescript-coding)"
• All plugin skills: "Skill(plugin-name:*)" (e.g., "Skill(meta-work:*)")
• Specific plugin skill: "Skill(plugin-name:skill-name)" (e.g., "Skill(meta-work:prompting)")
• Note: Skill(*) may not work for plugin-scoped skills; use explicit names or plugin wildcards

Sandboxing

Sandboxing provides filesystem and network isolation to enhance security and reduce permission prompts.

Benefits

• Filesystem Isolation: Restricts Claude's access to specified directories
• Network Isolation: Limits network access to approved servers
• Reduced Prompts: Auto-approve commands within sandbox boundaries
• Protection: Mitigates risks like data exfiltration or malicious downloads

Configuration

Add sandboxing configuration to settings.json:

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "npm"],
    "network": {
      "allowUnixSockets": ["/path/to/socket"],
      "allowLocalBinding": false
    }
  }
}

Sandbox Options

• enabled: Enable bash sandboxing (default: false)
• autoAllowBashIfSandboxed: Auto-approve bash commands when sandboxed (default: true)
• excludedCommands: Commands that should run outside the sandbox
• network.allowUnixSockets: Accessible Unix socket paths within sandbox
• network.allowLocalBinding: Allow binding to localhost ports (macOS only, default: false)

Best Practices

Security

1. Deny Dangerous Operations: Block destructive commands (rm -rf, sudo, etc.)
2. Protect Sensitive Files: Deny access to .env, credentials, secrets
3. Use Sandboxing: Enable sandboxing for enhanced security
4. Principle of Least Privilege: Grant minimum permissions needed

Productivity

1. Allow Common Commands: Pre-approve frequently used git/npm commands
2. Pattern Matching: Use wildcards for command families (Bash(git:*)
3. Team Consistency: Check settings.json into source control for team-wide permissions
4. Exclude from Sandbox: Add trusted commands to excludedCommands if needed

Organization

1. Project-Level: Use .claude/settings.json for project-specific permissions
2. User-Level: Use ~/.claude.json for personal preferences
3. Documentation: Document why specific permissions are granted
4. Regular Review: Periodically review and audit permissions

Examples

Allow Git Operations

{
  "permissions": {
    "allow": [
      "Bash(git status)",
      "Bash(git diff:*)",
      "Bash(git commit -m:*)",
      "Bash(git push origin:*)"
    ],
    "ask": ["Bash(git push --force:*)", "Bash(git rebase:*)"]
  }
}

Protect Sensitive Files

{
  "permissions": {
    "deny": [
      "Read(.env*)",
      "Write(.env*)",
      "Read(./secrets/**)",
      "Read(~/.ssh/**)",
      "Read(~/.aws/credentials)"
    ]
  }
}

Safe Development Environment

{
  "permissions": {
    "allow": [
      "Read",
      "Write",
      "Edit",
      "Bash(git:* except: git push --force, git rebase)",
      "Bash(pnpm:* except: pnpm remove)"
    ],
    "deny": ["Read(.env*)", "Bash(rm -rf /)", "Bash(sudo:*)"],
    "ask": ["Bash(git push --force:*)", "Bash(docker run:*)"]
  },
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git"]
  }
}

Allow All Skills and Commands

{
  "permissions": {
    "allow": [
      "SlashCommand(*)",
      "Skill(analyze-size)",
      "Skill(brainwriting)",
      "Skill(scratchpad-fetch)",
      "Skill(timestamp)",
      "Skill(typescript-coding)",
      "Skill(meta-work:*)",
      "Skill(development-lifecycle:*)"
    ]
  }
}

Skills and Agents

Skill-Level Permissions

Skills can restrict tool access using allowed-tools in frontmatter:

---
name: safe-reader
description: Read-only file operations
allowed-tools: Read, Grep, Glob
---

Agent-Level Permissions

Agents (subagents) can be configured with specific tool permissions at:

• User-level: ~/.claude/agents/ (available across all projects)
• Project-level: .claude/agents/ (shareable with team)

Each agent can have custom prompts and tool permissions defined in their YAML frontmatter.

Troubleshooting

Permission Denied

• Check settings.json for deny rules matching the operation
• Verify permission pattern matches the command/file path
• Check both project-level and user-level settings files

Too Many Prompts

• Enable sandboxing to reduce prompts
• Add frequently used commands to allow list
• Use pattern matching for command families

Sandbox Not Working

• Verify sandbox.enabled is true
• Check excludedCommands if commands should run outside sandbox
• Ensure network restrictions aren't blocking needed connections

References

• Claude Code Permissions Documentation
• Claude Code Settings Documentation
• Sandboxing Documentation
• Agent Skills Documentation