---
slug: "pi-restrict-bash"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/kotarac/pi-restrict-bash@master/README.md"
repo: "https://github.com/kotarac/pi-restrict-bash"
source_file: "README.md"
branch: "master"
---
# pi-restrict-bash

Opinionated restrictions for [Pi](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent)’s built-in `bash` tool.

The extension blocks common “escape hatches”, risky shell features, and context-exploding commands, nudging the agent toward Pi’s structured tools (`read`, `edit`, `write`) and toward using `rg` (via `bash`) for searching/listing.

## What it does

The extension intercepts tool calls and blocks:

- Tool calls to `grep`, `find`, and `ls`
- `bash` commands that use unsafe shell features (for example command substitution, variable expansion, redirects, background execution, subshell syntax, and control-flow keywords)
- `bash` commands that invoke disallowed programs (for example `sudo`, nested shells like `bash`/`sh`/`zsh`, `cat`, `tee`, `xargs`, `nl`, `fd`/`find`/`grep`/`ls`/`tree`)
- `bash` wrapper commands like `eval`, `exec`, `nohup`, `timeout`, `time`, `watch`, and `stdbuf`
- command-runner launchers like `npx`, `uvx`, `bunx`, `pnpx`, `pnpm dlx`, `yarn dlx`, `npm exec`, `bun x`, `uv tool run`, and scaffolding launchers like `npm create`/`npm init`/`yarn create`/`pnpm create`/`bun create` (`pnpm exec` and `yarn exec` are intentionally allowed)
- `git` subcommands that can mutate the working tree or repository (and `git grep`, since `rg` is preferred)
- `sed -i` / `sed --in-place`

When a command is blocked, Pi shows a reason string explaining what was denied.

## Install

This repo is a Pi package (see `package.json#pi.extensions`). Once installed, Pi auto-discovers and loads the extension.

Global install (writes to `~/.pi/agent/settings.json`):

- From GitHub:
  - `pi install git:github.com/kotarac/pi-restrict-bash`
- From npm:
  - `pi install npm:pi-restrict-bash`

Project-local install (writes to `.pi/settings.json` in your project):

- From GitHub:
  - `pi install -l git:github.com/kotarac/pi-restrict-bash`
- From npm:
  - `pi install -l npm:pi-restrict-bash`

## Try without installing

Try the package for a single run:

- From GitHub:
  - `pi -e git:github.com/kotarac/pi-restrict-bash`
- From npm:
  - `pi -e npm:pi-restrict-bash`

## Notes

- This is not a replacement for proper sandboxing. It only applies guardrails to Pi tool usage and serves as guidance for LLMs; it does not make executing untrusted code safe.
- You’ll likely want to pair this with system instructions that strongly prefer Pi’s structured tools (`read`, `edit`, `write`), and for searching/listing prefer `rg` (for example `rg`, `rg --glob`, `rg --files`, `rg --files --glob`) invoked via the `bash` tool.
- Many restrictions are about keeping tool output and shell behavior predictable so it doesn’t explode the LLM context (for example `find`/`ls`/`tree`, pipelines, redirects, and wrapper commands).
- This extension is intentionally strict. If you need to loosen rules, fork and adjust `forbiddenRules` / `blockedTools` in `extensions/restrict-bash.ts`.
- Extensions execute with full system permissions. Only install code you trust.

## License

GPL-2.0-only