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

• Deny Dangerous Operations: Block destructive commands (rm -rf, sudo, etc.)

• Protect Sensitive Files: Deny access to .env , credentials, secrets

• Use Sandboxing: Enable sandboxing for enhanced security

• Principle of Least Privilege: Grant minimum permissions needed

Productivity

• Allow Common Commands: Pre-approve frequently used git/npm commands

• Pattern Matching: Use wildcards for command families (Bash(git:* )

• Team Consistency: Check settings.json into source control for team-wide permissions

• Exclude from Sandbox: Add trusted commands to excludedCommands if needed

Organization

• Project-Level: Use .claude/settings.json for project-specific permissions

• User-Level: Use ~/.claude.json for personal preferences

• Documentation: Document why specific permissions are granted

• 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