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].

Wrapper	Source
pi-must-win	osolmaz/pi-must-win at an immutable commit
regrafter-driver	osolmaz/pi-regraft at an immutable commit
workflows	@osolmaz/pi-workflows 0.16.7
demo-mode	osolmaz/pi-demo-mode at 8f18a38
anti-repeat	osolmaz/pi-anti-repeat at f5406c3

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