pi-defer-modal

A Pi extension that defers modal dialogs while you're typing, preventing interruptions to your workflow.

Problem

When extensions display modal dialogs (using ctx.ui.select(), ctx.ui.confirm(), or ctx.ui.input()), these modals grab keyboard focus immediately. If you're in the middle of typing a message, the modal interrupts your typing — keystrokes land in the modal instead of the editor, breaking your train of thought.

Solution

This extension intercepts modal calls from any extension and defers them until you pause typing or submit your input. The tool calls stay blocked (as they should), but the UI presentation is delayed until you're ready.

Features

• Non-interrupting modals: Modals wait until you pause typing before appearing
• Configurable modal types: Choose which modal types to defer (select, confirm, input, custom)
• Adjustable timing: Configure how long to wait after your last keystroke
• Safety ceiling: Maximum deferral time prevents tools from hanging indefinitely
• Status indicator: Optional visual indicator when modals are being deferred
• Works with any extension: Transparently intercepts modals from all extensions

Installation

From npm (recommended)

pnpm add pi-defer-modal

Manual installation

1. Clone or download this repository
2. Place the pi-defer-modal directory in one of Pi's extension locations:
   • Project-local: .pi/extensions/pi-defer-modal/
   • Global: ~/.pi/agent/extensions/pi-defer-modal/

Configuration

Create a config.json file in the extension directory:

{
  "enabled": true,
  "modalTypes": ["select", "confirm", "input", "custom"],
  "quietMs": 1500,
  "maxDeferMs": 30000,
  "showStatusIndicator": true,
  "statusText": "⏸ modal pending — pause to review",
  "debug": false
}

Configuration Options

Option	Type	Default	Description
enabled	boolean	false	Enable or disable modal deferral
modalTypes	string[]	["select", "confirm", "input", "custom"]	Which modal types to defer
quietMs	number	1500	Milliseconds of inactivity before showing deferred modals
maxDeferMs	number	30000	Maximum time to defer a modal (prevents hanging)
showStatusIndicator	boolean	true	Show a status indicator when modals are deferred
statusText	string	"⏸ modal pending — pause to review"	Text to show in the status indicator
debug	boolean	false	Show extension diagnostic notifications

Configuration Locations

Configuration is resolved by @graelo/pi-ext-config@^0.2.0, which checks these locations in order of priority (first found wins):

1. Repository root: <git-root>/.pi/extensions/pi-defer-modal/config.json (only when the project is trusted)
2. Agent directory: <agent-dir>/extensions/pi-defer-modal/config.json (always available)

The git root is found by walking up from the current working directory until a .git marker is encountered (a directory in a normal clone, a file in worktrees and submodules). This means the config will be found regardless of which subdirectory of your repository you run Pi from. The agent directory defaults to Pi's own getAgentDir(), which honors PI_CODING_AGENT_DIR and expands a leading ~.

Project Trust: Project-tier configuration (location 1) is only considered when ctx.isProjectTrusted() returns true. This ensures that untrusted projects cannot override your global configuration. Global configuration remains available regardless of project trust status.

Commands

/defer-modal-toggle

Toggle modal deferral on or off.

/defer-modal-toggle

/defer-modal-config

Show the current configuration.

/defer-modal-config

/defer-modal-reload

Reload configuration from file (useful after editing config.json).

/defer-modal-reload

How It Works

1. Typing Tracking: The extension subscribes to ctx.ui.onTerminalInput to track when you type
2. Modal Interception: It wraps the UI methods (select, confirm, input) to intercept modal calls
3. Deferral Logic: When a modal is called, if you're actively typing, the extension waits until:
   • You pause typing for quietMs milliseconds, OR
   • You submit your input (press Enter), OR
   • The maximum deferral time (maxDeferMs) elapses
4. Status Indicator: While waiting, an optional status message shows that modals are pending

Example Usage

With this extension enabled:

1. You start typing a command: git commit -m "fix: ...
2. An extension (like pi-permission-system) tries to show a permission modal
3. Instead of interrupting you, the modal waits
4. You finish typing and pause for 1.5 seconds (default quietMs)
5. The permission modal appears, ready for your input

custom modal type

The custom type covers inline keybind dialogs rendered via ctx.ui.custom(). This is the method used by pi-permission-system for its permission prompts in TUI mode. Without wrapping custom, those prompts would interrupt your typing just like un-wrapped select/confirm/input would.

Compatibility

• Works with Pi v0.2.0 and later
• Requires @graelo/pi-ext-config@^0.2.0 or later for trust-aware config resolution
• Compatible with all extensions that use standard UI modal methods
• No changes required to existing extensions

Development

# Install dependencies
pnpm install

# Type check (there is no build step: Pi loads src/index.ts directly)
pnpm run check

# Tests
pnpm test

License

MIT