ai-fs-permissions

A platform-agnostic security tool that enforces file system permissions for AI agents. Designed to protect sensitive files and folders from unauthorized access by AI coding assistants.

Why?

When using AI coding assistants like Claude Code, Gemini CLI, or Cursor, you might want to:

• Protect configuration folders (.centy, .claude, .github)
• Make certain files read-only (lock files, configs)
• Block access to sensitive files (.env, secrets, keys)
• Allow read but block write to specific paths

This package provides a CLI that can enforce these permissions, working with any AI tool that supports command hooks.

Installation

pnpm add -g ai-fs-permissions

Or use without installation via pnpm dlx ai-fs-permissions or npx ai-fs-permissions.

Quick Start

# Check if writing to .centy is allowed
ai-fs-permissions --op write --path ".centy/config.json"
# Exit code: 2 (blocked if configured)

# Check if reading is allowed
ai-fs-permissions --op read --path "src/index.ts"
# Exit code: 0 (allowed)

# Show current configuration
ai-fs-permissions --show-config

Configuration

Create .ai-fs-permissions.yaml in your project root:

version: 1

rules:
  # Protect centy configuration (read-only)
  - path: ".centy/**"
    access: read
    reason: "Configuration folder - modifications may break tooling"

  # Protect AI agent settings
  - path: ".claude/**"
    access: read
    reason: "AI agent settings - must be modified by user only"

  # Block all access to env files
  - path: "**/.env*"
    access: none
    reason: "Environment secrets - sensitive data"

  # Block key files using regex
  - path: "^.*\\.key$"
    type: regex
    access: none
    reason: "Key files contain sensitive credentials"

  # Allow specific file within protected folder (negation)
  - path: "!.centy/user-config.yaml"
    access: readwrite
    reason: "User-editable config"

Access Levels

| Level | Read | Write | Description | |-------|------|-------|-------------| | none | Blocked | Blocked | Fully blocked | | read | Allowed | Blocked | Read-only | | write | Blocked | Allowed | Write-only (rare) | | readwrite | Allowed | Allowed | Full access |

Config Discovery

Configs are discovered gitignore-style and merged:

1. ~/.config/ai-fs-permissions/config.yaml (user defaults)
2. Walk up from cwd to find .ai-fs-permissions.yaml (project)
3. ./.ai-fs-permissions.yaml (current directory, highest priority)

Set extends: false in project config to ignore user defaults.

Platform Integration

Claude Code

Add to your .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read|Glob|Grep",
        "hooks": [
          {
            "type": "command",
            "command": "npx ai-fs-permissions --op read"
          }
        ]
      },
      {
        "matcher": "Edit|Write|NotebookEdit",
        "hooks": [
          {
            "type": "command",
            "command": "npx ai-fs-permissions --op write"
          }
        ]
      }
    ]
  }
}

Gemini CLI

Add to your .gemini/settings.json:

{
  "hooks": {
    "BeforeTool": [
      {
        "matcher": "read_file",
        "hooks": [
          {
            "type": "command",
            "command": "npx ai-fs-permissions --op read"
          }
        ]
      },
      {
        "matcher": "write_file|edit_file",
        "hooks": [
          {
            "type": "command",
            "command": "npx ai-fs-permissions --op write"
          }
        ]
      }
    ]
  }
}

Cursor

Create .cursor/hooks.json:

{
  "version": 1,
  "hooks": {
    "beforeShellExecution": [
      {
        "command": "npx ai-fs-permissions --op write"
      }
    ]
  }
}

CLI Options

ai-fs-permissions [options] [path]

Options:
  --op <type>       Operation to check: read, write (required)
  --path <path>     File path to check
  --config <path>   Use specific config file (skip discovery)
  --show-config     Show merged configuration and exit
  --validate        Validate config file and exit
  --help, -h        Show help message
  --version, -v     Show version

Input Methods:
  1. Command line:  ai-fs-permissions --op write --path ".centy/config.json"
  2. Stdin (JSON):  echo '{"tool_input":{"file_path":"..."}}' | ai-fs-permissions --op write
  3. Stdin (plain): echo ".centy/config.json" | ai-fs-permissions --op write

Exit Codes

• 0 - Operation allowed
• 2 - Operation blocked
• 1 - Error occurred

Blocked Message

When an operation is blocked, a clear message is output to guide the AI agent:

PERMISSION DENIED: Writing to '.centy/settings.json' is blocked.

Reason: Configuration folder - modifications may break tooling

This rule is configured by the project owner and cannot be overridden.
Do NOT attempt to:
- Use Bash commands to bypass this restriction
- Suggest workarounds that modify this path
- Ask the user to disable this protection

If this file must be modified, ask the user to do it manually.

License

MIT

Related Projects

• block-no-verify - Block --no-verify flag in git commands