10.5 Permission Profiles

Course: Claude Code - Power User Section: Customizing Claude Code Video Length: 2-5 minutes Presenter: Daniel Treasure

Opening Hook

Claude is powerful. It can read files, write code, run bash, execute commands. Not everyone should have the same capabilities. A code reviewer needs to read the codebase but not deploy to production. A CI bot needs to run tests but not delete files. Permission profiles let you define exactly what Claude can do in each context.

Key Talking Points

1. What Are Permission Profiles?

Predefined sets of allow/deny/ask rules
Control tools: bash, read, write, git, deploy, etc.
Can be set per-user, per-project, or per-role
Enable safe delegation: "Claude can help, but within guardrails" What to say: "Permissions are about trust and safety. You trust Claude to read your code, but not to push to production without asking. Profiles formalize that trust." What to show on screen: Permissions UI or settings file showing allow/deny rules. Show three profiles side-by-side: Development, Review-only, CI.

2. Built-in Profiles

Development: read/write all, run bash, git, model switching (full power)
Review-only: read-only, can suggest changes but not write, run read-only tools
Restricted: deny most tools, only answer questions, no file ops
CI/CD: read/write specific dirs, run bash/git, deny human interaction What to say: "You're not defining profiles from scratch. We've thought about common patterns. Pick the closest fit, then customize." What to show on screen: Show each profile's rules. Compare what each can do.

3. How Permissions Work: Allow, Ask, Deny

Allow: Claude automatically performs the action (read, write, bash)
Ask: Claude requests permission, you approve or deny (write to sensitive file, run dangerous command)
Deny: Claude cannot do this, period (no deployments, no secret writes) What to say: "Allow is fast. Ask is safe. Deny is absolute. Mix them based on context." What to show on screen: Three permission outcomes: Claude reading a file (allow), Claude asking before overwriting a config (ask), Claude unable to push to main (deny).

4. Setting Profiles at Different Levels

User-level: ~/.claude/permissions.json applies to all projects for that user
Project-level: .claude/permissions.json overrides user-level in this project
Role-level: different profiles for different users (maintainer vs. junior dev vs. reviewer)
Environment-level: CI has one profile, local development has another What to say: "A junior dev might have Review-only locally, but CI has broader permissions. Smart permissions scale trust with context." What to show on screen: Three settings files: user, project, and a third showing how CI env overrides them.

5. Real-world Use Cases

Code review bot: Review-only profile, can't modify code, only suggest
Feature development: Development profile, full tools, can refactor and commit
Security audit: Review-only plus bash for scanning, no writes
CI/CD deployment: Restricted to specific directories, can deploy but not delete
Documentation bot: Can read and write docs, not code What to say: "Good profiles match real workflows. If you're reviewing code from external contributors, limit permissions. If it's your own prototype, go full speed." What to show on screen: Scenario flow: show what each profile allows in common workflows.

Demo Plan

Show built-in profiles and explain each rule
Create a custom profile by editing ~/.claude/permissions.json or .claude/permissions.json
Set permission mode for the session (or get it from settings file)
Attempt an action that requires ask (e.g., write to config) and show Claude requesting permission
Attempt a denied action and show Claude refusing gracefully
Switch profiles and show behavior changes

Code Examples & Commands

Check current permissions:

cat ~/.claude/permissions.json
# or project-specific:
cat .claude/permissions.json

Built-in profile: Development

{
  "permissionMode": "development",
  "rules": {
    "read": "allow",
    "write": "allow",
    "bash": "allow",
    "git": "allow",
    "models": "allow",
    "deploy": "ask"
  }
}

Built-in profile: Review-only

{
  "permissionMode": "review-only",
  "rules": {
    "read": "allow",
    "write": "deny",
    "bash": "deny",
    "git": "ask",
    "models": "deny",
    "deploy": "deny",
    "suggest": "allow"
  }
}

Built-in profile: CI/CD

{
  "permissionMode": "ci",
  "rules": {
    "read": "allow",
    "write": {
      "default": "allow",
      "paths": ["/config", "/secrets"] // ask for these
    },
    "bash": "allow",
    "git": {
      "push": "ask",
      "force": "deny",
      "branches": ["main", "develop"]
    },
    "deploy": "allow",
    "humanInteraction": "deny"
  }
}

Custom profile: Documentation-only

{
  "permissionMode": "docs",
  "rules": {
    "read": "allow",
    "write": {
      "paths": ["docs/**", "README.md"],
      "other": "deny"
    },
    "bash": "deny",
    "git": {
      "commit": "ask",
      "push": "deny"
    },
    "deploy": "deny"
  }
}

Custom profile: Security Audit

{
  "permissionMode": "security-audit",
  "rules": {
    "read": "allow",
    "write": "deny",
    "bash": "allow",
    "bashBlacklist": ["rm -rf", "pkill", "dd"],
    "git": "allow",
    "models": "allow",
    "deploy": "deny",
    "focus": "security"
  }
}

Set profile via environment:

export CLAUDE_PERMISSION_MODE=review-only
claude chat "Review this for bugs"

# Or via settings
export CLAUDE_CONFIG_DIR=~/.claude/ci
# ~/.claude/ci/settings.json defines profile

View what Claude will/won't do:

claude permissions --profile review-only
# Output:
# Allow: read, suggest
# Deny: write, bash, git, deploy
# Ask: model-change

Gotchas & Tips

Gotcha: Permission changes don't affect current sessions. Start a new claude session to pick up permission changes.

Tip: Use "ask" liberally. If you're not sure, ask the human. It's better to interrupt than to refuse.

Tip: Document why a permission is denied. "Deploy denied because this isn't a trusted environment" is more helpful than just "denied".

Gotcha: Bash can bypass other permissions (e.g., bash can write files even if write is denied). If you deny bash, you're preventing CLI access entirely—consider "ask" instead.

Tip: Security-sensitive operations (deploy, delete, secret access) should be "ask" or "deny", never "allow".

Tip: Use path-based rules to allow fine-grained control. "Write allowed in src/, denied in config/" is more useful than binary allow/deny.

Lead-out

Permissions keep Claude safe and aligned with your risk tolerance. Next, we'll create team subagents—specialized Claude instances with different skills and personalities, each optimized for a specific role like code review, architectural guidance, or security audit.

Reference URLs

Permission profiles specification
Role-based access control (RBAC) concepts
Permission mode configuration
Path-based permission rules

Prep Reading

What are the most risky operations Claude could perform in your project?
Who on your team should have different permission levels?
What would "development" vs. "review" vs. "production" profiles look like for your workflow?

Notes for Daniel: Permissions are about empowerment, not restriction. Frame them as "safety rails that let you scale trust." Show realistic scenarios where different profiles make sense. The demo should feel practical: "here's how I safely let Claude auto-generate commits but ask before pushing to main."

Quick Reference