@ifi/oh-pi-extensions

Core first-party extensions for pi.

Included extensions

This package includes extensions such as:

• answer / /answer:auto
• git-guard
• auto-session-name
• custom-footer
• tool-metadata
• compact-header
• external-editor / /external-editor
• auto-update
• bg-process (powered by @ifi/pi-background-tasks)
• usage-tracker
• scheduler
• btw / qq
• watchdog / safe-mode
• worktree

Install

pi install npm:@ifi/oh-pi-extensions

Or install the full bundle:

npx @ifi/oh-pi

What it provides

These extensions add commands, tools, UI widgets, background process handling, usage monitoring, scheduling features, tool execution metadata, external-editor integration, git worktree awareness, and runtime performance protection (/watchdog, /watchdog:blame, /safe-mode) to pi.

bg-process now delegates to the richer @ifi/pi-background-tasks runtime, so the core bundle also gets /bg, Ctrl+Shift+B, and the bg_task tool.

git-guard also blocks git bash invocations that are likely to open an interactive editor in agent environments (for example git rebase --continue without non-interactive editor overrides), preventing hangs before they happen.

Answer

The answer extension extracts questions from the last LLM response and presents them in an interactive Q&A overlay powered by @ifi/pi-shared-qna.

• /answer — scan the last assistant message for questions, then show a Q&A overlay to fill in answers
• /answer:auto — toggle auto-detection: when enabled, questions in the final LLM response automatically trigger the Q&A overlay

Answers are injected back into the session as a follow-up user message. The extension uses an LLM call to extract structured questions (with optional multiple-choice options) from the response text, then renders them with the same QnA TUI component used by plan mode's request_user_input tool.

External editor

The external-editor extension adds:

• /external-editor — open the current draft in $VISUAL or $EDITOR
• /external-editor status — show the configured editor and available bindings
• Ctrl+Shift+E — open the current draft in the configured external editor

When the editor exits successfully, the updated text is synced back into pi's main draft editor. This complements pi's built-in app.editor.external binding (Ctrl+G by default) with a discoverable slash command and an extra shortcut.

Worktree

The worktree extension adds centralized git worktree awareness for oh-pi:

• /worktree or /worktree status — show the canonical repo root, current worktree root, and pi ownership metadata
• /worktree list — list all repo worktrees and distinguish pi-owned vs external/manual checkouts
• /worktree open [branch|path] — open a selected worktree in the system file opener and print a cd fallback
• /worktree create <branch> [purpose] — create a pi-owned worktree under shared pi storage with owner + purpose metadata
• /worktree cleanup <branch|path|id|all> — remove pi-owned worktrees while leaving external/manual worktrees alone by default

pi-owned worktrees are stored under shared pi storage using a workspace-mirrored root so every repo gets a stable namespace. Each managed worktree records which pi instance/session created it and why.

Scheduler follow-ups

The scheduler extension adds recurring checks, one-time reminders, and the LLM-callable schedule_prompt tool so pi can schedule future follow-ups like PR, CI, build, or deployment checks. Tasks run only while pi is active and idle, and scheduler state is persisted in shared pi storage using a workspace-mirrored path.

Use continueUntilComplete: true (plus optional completionSignal, retryInterval, and maxAttempts) when a scheduled check should keep retrying until completion is detected.

Package layout

extensions/

Pi loads the raw TypeScript extensions from this directory.

Scheduler ownership model

The scheduler distinguishes between instance-scoped tasks and workspace-scoped tasks. Instance scope is the default for /loop, /remind, and schedule_prompt, which means tasks stay owned by one pi instance and other instances restore them for review instead of auto-running them. Workspace scope is an explicit opt-in for shared CI/build/deploy monitors that should survive instance changes in the same repository.

When another live instance already owns scheduler activity for the workspace, pi prompts before taking over. You can also manage ownership explicitly with:

• /schedule:adopt <id|all>
• /schedule:release <id|all>
• /schedule:clear-foreign

Use workspace scope sparingly for long-running shared checks like CI/build/deploy monitoring. For ordinary reminders and follow-ups, prefer the default instance scope.

Usage tracker

The usage-tracker extension is a CodexBar-inspired provider quota and cost monitor for pi. It shows provider-level rate limits for Anthropic, OpenAI, and Google using pi-managed auth, while also tracking per-model token usage and session costs locally.

Usage-tracker persists rolling 30-day cost history and the last known provider rate-limit snapshot under the pi agent directory. That lets the widget and dashboard survive restarts and keep showing recent subscription windows when a live provider probe is temporarily rate-limited or unavailable.

Key usage-tracker surfaces:

• widget above the editor for at-a-glance quotas and session totals
• /usage for the full dashboard overlay
• Ctrl+Shift+U as a shortcut for the same overlay
• /usage-toggle to show or hide the widget
• /usage-refresh to force fresh provider probes
• usage_report so the agent can answer quota and spend questions directly

Watchdog config

The watchdog extension reads optional runtime protection settings from a JSON config file in the pi agent directory. That config controls whether sampling is enabled, how frequently samples run, and which CPU, memory, and event-loop thresholds trigger alerts or safe-mode escalation.

Path to the optional watchdog JSON config file under the pi agent directory. This is the default location used for watchdog sampling, threshold overrides, and enable/disable settings.

~/.pi/agent/extensions/watchdog/config.json

Example:

{
	"enabled": true,
	"sampleIntervalMs": 5000,
	"thresholds": {
		"cpuPercent": 85,
		"rssMb": 1200,
		"heapUsedMb": 768,
		"eventLoopP99Ms": 120,
		"eventLoopMaxMs": 250
	}
}

Watchdog alert behavior

The watchdog samples CPU, memory, and event-loop lag on an interval, records recent samples and alerts, and can escalate into safe mode automatically when repeated alerts indicate sustained UI churn or lag. Toast notifications are intentionally capped per session; ongoing watchdog state is kept visible in the status bar and the /watchdog overlay instead of repeatedly spamming the terminal.

Watchdog helper behavior

Load watchdog config from disk and return a safe object. Missing files, invalid JSON, or malformed values all fall back to an empty config so runtime monitoring can continue safely.

Resolve the effective watchdog thresholds by merging optional config overrides onto the built-in default thresholds.

Resolve the watchdog sampling interval in milliseconds, clamping configured values into the supported range and falling back to the default interval when no valid override is provided.

Notes

This package ships raw .ts extensions for pi to load directly.

Auto session naming and compaction continuity

auto-session-name now keeps session titles fresh as work focus changes, triggers a continue follow-up after compaction, and emits canonical resume hints with pi --session <session-id> whenever you switch sessions or exit.