pi-read-only

A pi extension that provides commands to toggle between read-only and read-write modes with full bash command filtering.

Features

• /read-only - Disables edit and write tools, restricts bash to safe read-only commands
• /read-write - Restores full access to all tools and unrestricted bash
• Bash allowlist - Only safe commands like cat, grep, ls, git status/diff/log are allowed
• State persistence - Mode persists across session reloads, branch navigation, and forking
• Safety net - Tool calls are blocked at the event level even if they somehow get through

Installation

Option 1: User-wide installation

cd ~/.pi/agent/extensions
git clone <repository-url> pi-read-only
cd pi-read-only
npm install

Option 2: Project-specific installation

cd /path/to/your/project
mkdir -p .pi/extensions
cd .pi/extensions
git clone <repository-url> pi-read-only
cd pi-read-only
npm install

Then add to your project's .pi/config.json:

{
  "extensions": ["./extensions/pi-read-only/index.ts"]
}

Usage

Once installed, the extension registers two slash commands:

/read-only   - Enable read-only mode (disable edit/write, restrict bash)
/read-write  - Disable read-only mode (restore full tool and bash access)

Example workflow

1. Start a session and safely explore a codebase:

   /read-only

2. Read files, search with grep, check git status, etc. The LLM cannot:

   • Edit files (edit tool disabled)
   • Write new files (write tool disabled)
   • Run destructive bash commands (see blocked list below)

3. When you're ready to make changes:

   /read-write

4. Now the LLM has full access to all tools and bash commands.

Bash Command Filtering

In read-only mode, bash commands are filtered against an allowlist:

Allowed commands

• File viewing: cat, head, tail, less, more
• Search/list: grep, find, ls, tree, rg, fd
• System info: pwd, wc, sort, uniq, diff, file, stat, du, df
• Git (read-only): git status, git log, git diff, git show, git branch
• Package managers (read-only): npm list, yarn info, pip list, etc.
• Network (read-only): curl, wget -O -
• And more...

Blocked commands

• File modification: rm, mv, cp, mkdir, touch, chmod, tee
• Git (write): git add, git commit, git push, git pull, git merge
• Package managers (write): npm install, pip install, apt install, brew install
• Redirections: >file, >>file
• Editors: vim, nano, code
• System: sudo, su, kill, reboot, shutdown, systemctl start/stop
• And more...

How it works

1. Tool control - Uses pi.setActiveTools() to disable edit and write
2. Bash filtering - Uses pi.on("tool_call") to block dangerous bash commands
3. State persistence - Uses pi.appendEntry() to save state across session operations

Safety notes

• The extension blocks commands at the tool call level - this catches most cases
• Complex bash commands with pipes/semicolons may bypass simple pattern matching
• For truly untrusted code, use containerization or VMs

License

MIT