pi-mono is a monorepo of opinionated extensions for the Pi coding agent. Fork or clone it, then adapt the extensions to your workflow. The workspace has instructions and skills for coding agents, so Pi can make the changes for you.
To try the extensions as they are, install the release branch. It has all extensions without the development files, and Pi installs it like any other package.
Only Linux support is guaranteed. Windows and macOS are not thoroughly tested.
| Extension | What it does |
|---|---|
| pi-subagents | Delegates foreground and background work to resumable Pi processes, with task views and cancellation. |
| pi-smart-compact | Lets the model compact its own context mid-task, so long tasks keep going. |
| pi-skills | Turns /skill:<name> anywhere in a prompt into a file link, with Tab completion. |
| pi-tool-display | Shows tool calls as compact, expandable cards with file diffs. |
| pi-nested-instructions | Loads AGENTS.md files from subdirectories when the model starts working in them. |
| pi-profiles | Switches the model, thinking level, tools, and instructions together with one key. |
| pi-fff-guard | Stops FFF searches that would silently find nothing in ignored or missing paths. |
| pi-null-args | Drops optional tool arguments that a model sent as the text "null", so Pi doesn't reject the call. |
| pi-read | Lets the model select and highlight an exact span of a file when reading it. |
| pi-model-prompt | Appends different system instructions depending on the model. |
| pi-todo | Gives the model a todo list, shown in a widget and a /todos browser and saved in the session. |
| pi-prompt-manager | Keeps searchable prompt history and saved drafts per directory. |
| pi-session-utils | Saves unsaved sessions, starts empty child sessions, and names sessions automatically. |
| pi-abort-guard | Stops a running agent only on a second Escape, so one stray press doesn't end the turn. |
| pi-agent-summary | Adds a one-line summary after each run: time, models, commands, and changed files. |
| pi-editor-widgets | Moves widgets and statuses above the editor, below it, or into the footer. |
| pi-prompt-cloak | Rewrites two Pi-specific system prompt lines to reduce fingerprinting by upstream providers. |
To change the extensions, remove them, or add your own, fork or clone this repository and develop in it. The workspace is the source of the release branch, so your copy has the same extensions, tests, and checks.
The workspace has instructions and skills for coding agents:
- The root
AGENTS.mdlinks the agent to the guidance for its task, such as architecture, testing, or verification. - Extensions and shared packages with non-obvious boundaries have their own
AGENTS.mdwith those boundaries and their checks. With pi-nested-instructions loaded, Pi adds that file when the agent starts to work in the package. .agents/skills/has skills that review changes and move the workspace to a newer Pi release. Pi finds them when it runs in the workspace. Run one with/skill:<name>, such as/skill:code-review.
Use Node.js from .node-version and the Vite+ CLI (vp). From the repository root:
vp install --frozen-lockfilePi loads extensions from their TypeScript source, so there's no build step.
Run the workspace copy of Pi with an extension directory:
vp exec pi -e ./packages/extensions/pi-tool-displayRepeat -e to load more extensions. To keep extensions loaded across launches, use Pi's package installation.
Links to published Pi documentation point to the latest version, which can be newer than the version that this workspace uses. Maintainers can check the installed API references for the pinned version.
Each push to master runs the release workflow, which checks the workspace and builds the release branch. In your own repository, it builds your own release branch. Install that branch with your repository in place of pnd280/pi-mono. GitHub turns off workflows in a new fork until you enable them on its Actions tab.
| When you… | Read |
|---|---|
| Run checks, edit tooling, or add dependencies | Development |
| Write extension code against Pi's API | Pi's extension documentation, then the workspace's Pi API contracts |
| Find the package that owns a feature | Architecture |
Install all extensions as one Pi package from the release branch:
pi install git:github.com/pnd280/pi-mono@releaseTo try the extensions for one session without installing them, run pi -e git:github.com/pnd280/pi-mono@release.
To load only some extensions, install the package and turn the others off with pi config. Or list the extensions to load in ~/.pi/agent/settings.json:
{
"packages": [
{
"source": "git:github.com/pnd280/pi-mono@release",
"extensions": ["extensions/pi-todo/index.ts", "extensions/pi-read/index.ts"]
}
]
}Write each path in full, because index.ts alone matches every extension. Pi's package filters describe the other pattern forms.
pi update --extensions moves the installation to the newest release commit. pi update alone updates only Pi. Pi counts a source with a branch as pinned, so it doesn't report new commits at startup.
To stay on one version, install its tag, such as git:github.com/pnd280/pi-mono@v0.1.0. pi update --extensions keeps a tag; to change the version, install another tag. To stay on a build between versions, install its commit with the full 40-character hash. Pi fetches the ref again on update, and Git can't fetch an abbreviated hash.
With all extensions loaded, Pi shows two warnings at each start. pi-profiles replaces Pi's built-in tool-search extension; its tool search section tells how to stop the warning. pi-prompt-manager takes Ctrl+R from session renaming; its configuration sets other keys.