pi-keeper
Permission modes for pi (default, auto and plan) with per-project allow, ask and deny rules and a plan you approve before any edit.
Package details
Install pi-keeper from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:pi-keeper- Package
pi-keeper- Version
0.1.3- Published
- Nov 21, 2026
- Downloads
- 700/mo · 700/wk
- Author
- novram
- License
- Apache-2.0
- Types
- extension, prompt
- Size
- 950 KB
- Dependencies
- 0 dependencies · 3 peers
Pi manifest JSON
{
"image": "https://raw.githubusercontent.com/DanielBlei/pi-packages/main/pi-keeper/assets/preview.png",
"prompts": [
"./prompt-templates"
],
"extensions": [
"./extensions/index.ts"
]
}Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
pi-keeper
Permission modes and a project rulebook for pi: default, auto and plan, per-project rules, and a plan → execute handoff. Each mode decides which tool calls run, which ask you, and which are blocked.
A personal project, shared as is. pi-keeper reduces accidental damage by asking before risky actions. It is not a sandbox or a security boundary. Run untrusted work in a container or a VM.
Install
pi install npm:pi-keeper
pi update --extensions picks up new releases. From a checkout, see Working from a checkout.
Modes
| Mode | Use it for | Runs without asking | Asks | Blocked |
|---|---|---|---|---|
default (blue) |
everyday work: you approve changes | reads, searches, read-only bash (loops and inline python included), anything your rules cover, read-only tools | edits, other bash, other tools | sudo & co |
auto (yellow) |
a trusted task you are watching | almost everything, including deletes inside the project | dangerous or destructive commands, protected paths, writes outside the project, secrets, the first outside read | sudo & co |
plan (green) |
researching and writing a plan | reads, read-only bash, the plan file, the scratch dir | other bash | edits, other tools, dangerous commands, sudo & co |
In plan mode the agent writes a plan file and calls exit_plan_mode; you then pick auto, or default with approval for each edit. The guide has the full action-by-action matrix.
Commands
| Command | What it does |
|---|---|
| Alt+M, Ctrl+Shift+M | Cycle default → auto → plan (Ctrl+Shift+M needs the kitty keyboard protocol) |
/mode |
Pick a mode |
/plan [prompt|open] |
Start plan mode, or open the plan |
/permissions |
List every rule with its source; remove the ones you pick |
/approvals |
Open the permission asks that background subagents are waiting on |
/rules |
Open the rulebook: rules that fire when the model slips |
/keeper [setting value] |
Settings panel, or set one directly |
Dialogs offer Yes once, Don't ask again this session, or Always allow … in this project, for commands as well as MCP and other tools. Project rules are saved to .pi/settings.local.json (default mode only). Session answers reach every subagent. ask and deny rules apply in every mode; allow rules load after you review the file once. Details: Managing rules, The dialogs, /keeper.
Optional companions
| Package | What it adds |
|---|---|
| pi-subagents | children run in your mode, and background asks reach your dialog (Subagents) |
| pi-shell-highlight | colored command names and heredocs in the permission dialog |
Without them pi-keeper works standalone.
Security and limitations
pi-keeper decides from the command text and tool arguments. A shell is too flexible for that to be complete, so it does not guarantee a harmful command is caught.
- No mode is bulletproof;
autolets the most through. Preferplanordefaultand add the narrowest rule that works. - Read each dialog before you approve it, and review changes before you commit, push or deploy.
- For untrusted code or unattended runs, isolate with a container, a VM or a separate user without your credentials.
Use at your own risk. Provided "AS IS", without warranties; see sections 7 and 8 of the LICENSE. Full text: guide.
Compatibility
Tested with pi 1.5.2, pi-subagents 0.89.0 and pi-cc-extensions 1.0.20. pi-cc-extensions can hide the plan row: list exit_plan_mode under excludeRenderers in its settings, or pi-keeper asks once per session. More in the guide.
More
Guide (every mode, dialog, rule and setting) · Design (reasoning and threat model) · Architecture · Rulebook · Development
Acknowledgements
Rule spellings such as Bash(git add:*) and WebFetch(domain:<host>) are read for compatibility with the settings format Claude Code documents. The modes, the plan flow and everything else are written from scratch; nothing here comes from Claude Code's code or prompts. The command arity table in extensions/modes.ts is adapted from OpenCode (MIT, see NOTICE). The rulebook's file shape is an idea from oh-my-pi; no code was taken. Built on pi. Not affiliated with or endorsed by Anthropic, OpenCode, oh-my-pi or the pi project; their names are used only to say what this works with or credits.
