OnurPi
OnurPi is Onur Solmaz's personal setup for the
Pi coding agent. It keeps the extensions, tools, skills, theme, and settings I
use for daily software work in one installable repository.
I build these packages for my own workflow, but each package is self-contained so others can use or
adapt the parts they want. More of my work is available at solmaz.io and on
GitHub.
Contents
| Package | Purpose |
|---|
@onurpi/agents | Personal agent instructions, skills, and cross-harness sync |
@onurpi/turn-fold | Bounded transcript replay and run-level folding |
@onurpi/anti-repeat | Detects and stops repeated work, including loops in streamed thinking |
@onurpi/live-stats | Braille spinner, shimmering working line, and live response metrics |
@onurpi/skill-slug | Invoke skills by typing their bare slug |
@onurpi/nyan-mode | Animated bitmap Nyan Cat context runway |
@onurpi/prompt-queue | Editable prompt queue, steer control, and history manager |
@onurpi/restart | Full Pi process restart on the exact persisted session |
@onurpi/pi-codex-compaction | OpenAI Codex native remote compaction (vendored) |
@onurpi/reliable-compaction | Stable transport policy for context compaction |
@onurpi/infinite-retry | Infinite capped retries with Alt+R manual wake |
@onurpi/onur-openclaw-maintainer | Read-only OpenClaw local-model issue workflow |
@onurpi/pi-usage | Multi-provider usage reports and model-gated usage status |
@onurpi/pi-session | Bounded, read-only recovery views for Pi sessions |
@onurpi/plan-checklist | Branch-aware model task plan with live progress |
@onurpi/unified-exec | Persistent shell and PTY sessions with race-free completion wake |
@onurpi/command-guard | Fail-closed checks for destructive shell commands |
@onurpi/permissions | Ask before a tool call that is not read-only, with a session toggle |
@onurpi/yarp | Prunes long output from supported developer commands |
@onurpi/pi-must-win | Pi attribution and Unified Exec integration |
@onurpi/workflows | Pinned workflow command and control tool |
@onurpi/demo-mode | Opt-in self-driving demo mode |
@onurpi/regrafter-driver | Regraft command and optional Regrafter delegation |
@onurpi/theme | Portable onur-dark Pi theme |
@onurpi/image-budget | Image re-encoding and eviction inside a request budget |
@onurpi/claudishlint | One plain rewrite for dense, Claudish model prose (vendored, off) |
@onurpi/focus-mode | Cap how many Pi agents work at the same time |
@onurpi/pi-tui-kit is a vendored library package (declarative Pi TUI
menus), not a Pi extension; it backs @onurpi/pi-usage and is not loaded as a Pi resource.
@onurpi/claudishlint is vendored and switched off. The package and its
tests stay in the repository, and the root Pi manifest does not list its entry point, so Pi does not
load it. To switch it on, add ./packages/claudishlint/index.ts to pi.extensions in the root
package.json and run npm run settings:reset followed by npm run settings:sync.
Included external extensions
OnurPi loads external extensions through private wrapper packages under packages/. Each wrapper
owns its upstream pin and any OnurPi-specific integration. Their source remains in the original
repositories.
Extensions that need no OnurPi-specific integration load directly from a pinned npm entry in
settings.json, such as npm:[email protected] and npm:[email protected].
Codex compaction has a single owner: pi-codex-compaction handles the built-in openai-codex
provider natively. reliable-compaction passes openai-codex through and keeps covering every
other model. See the
package README.
Demo Mode stays inactive unless PI_DEMO_MODE=1 is set. Regrafter stays out of ordinary prompts
unless its driver skill matches an explicit delegation or vendored-code maintenance request. YARP
stays inactive unless its yarp binary is on PATH; see the YARP package README.
Install
The root manifest registers every extension, personal skill, and the onur-dark theme, so one
package entry covers the whole workspace:
pi install git:github.com/osolmaz/onurpi
Installation creates ~/.local/bin/pi, which starts the restart-aware launcher and then the
upstream Pi runtime. Keep ~/.local/bin before the upstream Pi directory in PATH. Start one new
shell after the first installation so the shell resolves the new command path. The stable launcher
then survives upstream Pi reinstalls and keeps the normal pi command seamless.
Run /reload in an existing Pi session after installation. After new commits land on main, run
pi install git:github.com/osolmaz/onurpi again (or pi update --extensions) and /reload to pick
them up.
Pi loads public personal skills from @onurpi/agents. The agent installer reads
global instructions and private skills from a sibling private repository, then refreshes Pi, Codex,
Claude Code, and Cursor:
npm ci
npm run agents:sync
npm run agents:check
The private repository is required for instruction installation. OnurPi does not contain a global
AGENTS.md source.
Global settings
settings.json is the source-controlled copy of the global Pi settings at
~/.pi/agent/settings.json. Pi authentication, session history, trust decisions, and model-provider
state remain outside this repository. Review settings for credentials or machine-specific values
before committing future changes.
model-overrides.json is the source-controlled copy of the reviewed
per-model overrides from ~/.pi/agent/models.json. Only providers.<name>.modelOverrides is
copied. Endpoints, API keys, and model lists stay machine-local and are never written into this
repository.
web-search.json is the source-controlled copy of the reviewed pi-web-access
settings from ~/.pi/agent/web-search.json. Only the non-secret keys listed in TRACKED_KEYS are
copied. Provider API keys, the proxy URL, and auth settings stay machine-local. The tracked copy
turns the search curator off, so web_search returns results without opening a browser window.
These scripts keep the copies in agreement without ever leaking machine-local development state.
Both derive the canonical package entries from the root Pi resource manifest, so the list never
needs manual maintenance:
npm run settings:sync # reconcile the live files and the tracked copies in both directions
npm run settings:reset # force the repository values onto the live files
scripts/hf-context-floor.ts generates Hugging Face overrides
instead of hand-writing them: it reads the cached router catalog (~/.pi/agent/models-store.json)
and raises every model below the 272,000-token floor to it in the tracked model-overrides.json.
Models at or above the floor are never lowered, manual entries are preserved, and pure floor
artifacts are pruned on re-run. Run it after pi update --models picks up new catalog entries, then
reconcile with npm run settings:sync:
node scripts/hf-context-floor.ts
Pi has no provider-wide context override: modelOverrides keys on exact model IDs, and the model
registry hands out copies, so a runtime extension cannot patch model metadata. Generating the
per-model entries is the documented mechanism without maintaining them by hand.
sync compares the live files, the tracked copies, and the last reconciled state recorded in
~/.pi/agent/.onurpi-sync-base.json. A key that changed on one side is applied to the other, so a
change in the repository reaches the live files and a live change reaches the tracked copies without
a manual edit. When both sides changed the same key, sync reports the conflicting settings, writes
nothing, and exits non-zero. Choose the live value with npm run settings:sync -- --adopt-live, or
the repository value with npm run settings:reset.
The base file is machine-local and is not committed, so a fresh clone reconciles from scratch
instead of inheriting another machine's state. Until a base exists, sync refuses to guess between
two differing copies and asks for reset or --adopt-live. lastChangelogVersion is a
machine-local key: it stays in the live file and is never tracked.
An entry counts as belonging to this repo when it points into the main checkout, into an
onurpi-worktrees/ worktree, or at git:github.com/osolmaz/onurpi. The replaced sources for Goal,
Unified Exec, and Codex Usage are also treated as repo-owned so they cannot coexist with the
vendored packages. Those entries are replaced with one canonical
../../repos/onurpi/packages/<name> entry per registered extension or theme package. External
entries (npm packages, other git repos) and all other settings pass through untouched.
Unified Exec replaces Pi's built-in bash tool and the old shell-execution-policy package. Its
attachment windows stay bounded, while the underlying session remains alive until it exits, is
killed, reaches the session cap, or Pi shuts down. That long-lived process model is required for
servers, interactive programs, and finite jobs that take more than two minutes.
During development the live file may point anywhere, including a worktree or a dev-only package, and
sync still compares and writes the correct canonical values in the tracked copy.
Structure
Each extension and command-line tool is an independent package under packages/ with its own
package.json and entry point. Tests and a README live beside the source. The theme follows the
same package layout and registers its JSON file through pi.themes. The private root manifest
registers every Pi resource for workspace-wide development. See
Adding packages to OnurPi before adopting another local or external
package.
This workspace follows the package-directory structure used by
ogulcancelik/pi-extensions, while keeping shared
TypeScript quality tooling at the workspace root.
Development
Extensions are developed from a live Pi session. Edit a checkout, then run /reload. On this
machine the canonical install is per-package local paths into the main checkout, so /reload picks
up local edits directly. To develop in a worktree instead, point the live settings entry at the
worktree path; when done, npm run settings:reset restores the canonical entries, and sync never
records a worktree path in the tracked copy.
Quick-test without touching settings at all:
pi -e .
Quality gates:
npm ci
npm run check
npm run slophammer
Mutation testing remains available as an optional manual check:
npm run mutate
