pi-file-permissions

A pi extension that enforces path-based file permissions for pi's built-in tools using a simple YAML config.

Install / Uninstall

pi install npm:pi-file-permissions
pi remove npm:pi-file-permissions

Background: Pi's Built-in Tools

Pi ships with four default coding tools and three additional tools (disabled by default):

Tool	Default	Description
bash	✅ enabled	Execute shell commands
read	✅ enabled	Read file contents
write	✅ enabled	Create or overwrite files
edit	✅ enabled	Edit files with exact text replacement
find	❌ disabled	Find files by glob pattern
grep	❌ disabled	Search file contents with ripgrep
ls	❌ disabled	List directory contents

By default, all enabled tools have unrestricted access to the filesystem. This extension adds permission boundaries so you can control which paths each tool can reach.

How It Works

This extension is designed to do one simple thing: restrict which paths the LLM's tools can access. If you don't provide a file-permissions.yaml in your project root, nothing happens — pi runs completely normally.

Why This Matters

Pi's LLM often aggressively searches for files — sometimes scanning from $HOME or traversing large directory trees — which can be slow and wasteful. More importantly, when building focused agents or multi-agent systems, setting clear boundaries on which files each agent can access is critical. You want to define exactly which paths are read-only, which are editable, and which are completely off-limits. This prevents agents from stepping on each other's work and keeps each agent scoped to its responsibility.

Permission control is enforced at three levels:

1. System Prompt

On each prompt, the extension appends a File Permission Policy section to the system prompt. This tells the LLM upfront which paths are allowed and which tools can access them. It also instructs the LLM to never attempt workarounds (like using bash to run find or grep) when a tool is blocked.

2. Tool Descriptions

The extension overrides the built-in tool descriptions to include the allowed paths from your config. This way the LLM sees the restrictions directly in the tool definitions and avoids calling tools on paths it knows are denied.

The bash tool description is updated to explicitly forbid invoking file discovery or search commands (find, grep, rg, ls, tree, fd, ag, ack, locate). These should be done through the dedicated tools, which are subject to permission checks.

3. Tool Call Blocking

As a hard enforcement layer, the extension intercepts every tool call (tool_call event) and checks the target path against the config. If the path is not within an allowed domain, or the tool is not in that domain's permission list, the call is blocked before execution. The LLM receives the denial reason as the tool result.

For bash, the extension checks the command string for forbidden subcommands (like find, grep, ls, etc.) and blocks them to prevent workarounds.

Usage

Option A: file-permissions.yaml

Create a file-permissions.yaml in your project root:

domains:
  - path: /Users/me/projects/frontend
    permissions: [read, write, edit, find, grep, ls]
  - path: /Users/me/projects/backend
    permissions: [read, find, grep, ls]
  - path: ~/data/reports
    permissions: [read]
  - path: ./local-docs
    permissions: [read, find, ls]

Each path must be a path to a folder or file. The domain covers the path itself and everything under it. Paths can be:

• Absolute — /Users/me/projects/frontend
• Relative — ./local-docs (resolved against project root)
• Home directory — ~/data/reports (expands ~ to $HOME)

Option B: persona.yaml (pi-teammate)

If you're using pi-teammate — a peer-network multi-agent extension for pi — each agent already has a persona.yaml in its working directory. You can embed file permissions directly in that file using a domain key, eliminating the need for a separate file-permissions.yaml:

name: "Drew"
provider: "anthropic"
model: "claude-opus-4-6"
description: >
  Fullstack developer. Builds UI components and API integrations.
systemPrompt: >
  You are a senior fullstack developer.
domains:
  - path: /Users/me/projects/frontend
    permissions: [read, write, edit, find, grep, ls]
  - path: /Users/me/projects/shared-lib
    permissions: [read, find, grep]

The domains array follows exactly the same structure as in file-permissions.yaml. file-permissions.yaml takes priority if both files are present.

Rules

• Only "allow" semantics — listed paths get the listed permissions; everything else is denied
• No config file — everything is allowed, pi runs normally with no modifications
• Empty domains — domains: or domains: [] means no extra paths are allowed; only the project root and ~/.pi remain accessible
• persona.yaml without domains — if the key is absent entirely, no restrictions apply (the file is treated as a plain persona config)
• file-permissions.yaml takes priority — if both files are present and file-permissions.yaml is valid, persona.yaml is ignored
• Project root (cwd) — has full permission by default, but an explicit domain that covers it (or any ancestor of it) overrides this default with the domain's own permissions
• ~/.pi — has full permission by default (pi's own config directory); same override rule as above applies
• Explicit domains beat defaults — if a configured domain matches a path, that domain's permissions are the source of truth, even when the path lives inside cwd or ~/.pi
• Most specific wins — if a path matches multiple domains, the longest (most specific) path takes precedence

Available Permissions

Permission	Tool	Description
read	read	Read file contents
write	write	Create or overwrite files
edit	edit	Edit files with text replacement
find	find	Find files by glob pattern
grep	grep	Search file contents
ls	ls	List directory contents

Scope

This extension only controls access for pi's built-in file tools. It does not manage:

• Skills — on-demand capability packages loaded by the LLM
• MCP servers — external tool servers connected to pi
• Custom extension tools — tools registered by other extensions

If you need to control access to skills or MCP servers, install additional extensions designed for those purposes.

License

MIT