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

``bash
pnpm add -g ai-fs-permissions
`

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

Quick Start

`bash


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:

`yaml
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"
`

$3

| 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 |

$3

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

$3

Add to your .claude/settings.json:

`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"
}
]
}
]
}
}
`

$3

Add to your .gemini/settings.json:

`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"
}
]
}
]
}
}
`

$3

Create .cursor/hooks.json:

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

CLI Options

`
ai-fs-permissions [options] [path]

Options:
--op Operation to check: read, write (required)
--path File path to check
--config 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