Pin Pi coding agent extensions in an open source runtime

Where Pi puts an extension

Pi packages bundle extensions, skills, prompt templates and themes. They install from npm or git: pi install npm:@foo/pi-tools, or pi install git:github.com/badlogic/pi-doom (pi.dev/packages). Pi looks in ~/.pi/agent/extensions/ for every project and in .pi/extensions/ for one. Project-local entries load once the project is trusted. pi -e ./path.ts runs a single file for a quick test, and /reload picks up auto-discovered ones without a restart (Pi's extension docs).

An extension registers tools the model can call and adds commands. It intercepts tool calls and can block them, injects context, draws custom interface components, and keeps state across restarts. It can also register model providers or MCP servers. Pi ships four built-in tools: read, write, edit and bash. A permission gate is an extension deciding whether one of those four may fire.

What "same operating-system permissions" means

Pi's documentation states the trade in two sentences: "An extension runs inside the Pi process with the same operating-system permissions. It can inspect prompts, tool calls, files, credentials, and session history, so load extensions only from sources you trust." The same page puts it again as "Extensions run with your full system permissions and can execute arbitrary code."

In practice that covers the project files, the session transcript, and whatever credentials the process inherited. On a machine you run Pi on yourself, Pi reads provider keys from the environment, and a module loaded into the same process can read them. In Kortix, model provider keys and the ChatGPT subscription sign-in are spent server-side and never reach the sandbox, so what an extension can read in a session is that session's files and context, not a model key. Pi's README adds that the harness "does not include a built-in permission system for restricting filesystem, process, network, or credential access. By default, it runs with the permissions of the user and process that launched it." (earendil-works/pi)

The permission layer is a package

Pi's docs name permission gates (confirm before rm -rf, sudo), path protection (block writes to .env, node_modules/) and git checkpointing as example uses. Community walkthroughs install extensions called pi-permission-system, pi-undo-redo and pi-web-access. In those setups the permission layer arrives as a community package, loaded into the same process it is meant to police.

A gate you install still does useful work. It is code you can read and test before it loads. That is the check Pi's docs ask for when they say to load extensions only from sources you trust.

What the runtime around the list changes

In Kortix every new session runs pi. The packages are declared in harnesses.pi.packages, at most 20 entries, and an npm entry names an exact version. Kortix reads harnesses/pi/ for settings.json, extensions/, skills/ and prompts/, so an extension file can sit in the repository beside the manifest. The docs are direct about what the list does not buy: "Kortix loads a pi package as published. It does not test third-party packages." (Read the docs)

Tool calls then pass the agent's permission rules. Each tool is allow, ask or deny, bash patterns can be named one by one, and the most specific rule wins. Those rules govern the calls the model makes. A package that runs its own code is limited by the machine instead. Each session has its own isolated machine and branch, so an extension reaches that session's files rather than your laptop's. Connector credentials are brokered server-side and never enter the machine, and model provider keys are spent server-side rather than in the sandbox. Environment is the default exposure for a project secret. The values a module can read are the ones the session was given.

Two files decide the exposure: the package list in kortix.yaml and the permission block in the agent file. Both live in the repository. That makes them the part of a Pi setup a reviewer can read before the first session starts. Where the session itself runs is the other half, covered in running Pi in the cloud.