# @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

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

Or install the full bundle:

```bash
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

<!-- {=extensionsSchedulerOverview} -->

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.

<!-- {/extensionsSchedulerOverview} -->

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

## Package layout

```text
extensions/
```

Pi loads the raw TypeScript extensions from this directory.

## Scheduler ownership model

<!-- {=extensionsSchedulerOwnershipDocs} -->

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.

<!-- {/extensionsSchedulerOwnershipDocs} -->

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

<!-- {=extensionsUsageTrackerOverview} -->

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.

<!-- {/extensionsUsageTrackerOverview} -->

<!-- {=extensionsUsageTrackerPersistenceDocs} -->

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.

<!-- {/extensionsUsageTrackerPersistenceDocs} -->

<!-- {=extensionsUsageTrackerCommandsDocs} -->

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

<!-- {/extensionsUsageTrackerCommandsDocs} -->

## Watchdog config

<!-- {=extensionsWatchdogConfigOverview} -->

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.

<!-- {/extensionsWatchdogConfigOverview} -->

<!-- {=extensionsWatchdogConfigPathDocs} -->

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.

<!-- {/extensionsWatchdogConfigPathDocs} -->

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

Example:

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

### Watchdog alert behavior

<!-- {=extensionsWatchdogAlertBehaviorDocs} -->

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.

<!-- {/extensionsWatchdogAlertBehaviorDocs} -->

### Watchdog helper behavior

<!-- {=extensionsLoadWatchdogConfigDocs} -->

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.

<!-- {/extensionsLoadWatchdogConfigDocs} -->

<!-- {=extensionsResolveWatchdogThresholdsDocs} -->

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

<!-- {/extensionsResolveWatchdogThresholdsDocs} -->

<!-- {=extensionsResolveWatchdogSampleIntervalMsDocs} -->

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.

<!-- {/extensionsResolveWatchdogSampleIntervalMsDocs} -->

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