pi-sticky-input

pi-sticky-input is a Pi extension that keeps chat input, status widgets, editor content, and footer controls anchored while session history updates in a bounded viewport above them.

• npm: https://www.npmjs.com/package/pi-sticky-input
• GitHub: https://github.com/MasuRii/pi-sticky-input

Capabilities

• Keeps Pi's status, below-editor widgets, editor, and footer together in a sticky pane.
• Bounds rendered history above the sticky pane so long sessions do not push input off screen.
• Uses an alternate screen by default to avoid terminal scrollback fighting the sticky input layout.
• Supports keyboard history scrolling with PageUp, PageDown, Ctrl+PageUp, Ctrl+PageDown, Ctrl+Home, and Ctrl+End.
• Supports optional terminal mouse-wheel scrolling through alternate-scroll mode or SGR mouse capture.
• Falls back to Pi's original renderer for overlays and structurally unknown layouts.
• Keeps debug logging disabled by default and writes only to the extension-local debug/ directory when enabled.

Installation

npm package

pi install npm:pi-sticky-input

Git repository

pi install git:github.com/MasuRii/pi-sticky-input

Local extension folder

Place this folder in one of Pi's extension discovery paths:

| Scope | Path | |-------|------| | Global default | ~/.pi/agent/extensions/pi-sticky-input | | Project | .pi/extensions/pi-sticky-input |

Pi discovers the extension through the root index.ts entry listed in package.json, which forwards to src/index.ts.

Usage

The sticky renderer is enabled automatically when the extension loads and the TUI is available.

The /sticky-input command controls optional mouse-wheel capture at runtime:

/sticky-input status
/sticky-input mouse on
/sticky-input mouse off
/sticky-input mouse toggle
/sticky-input help

Keyboard history scrolling is enabled by default. Mouse-wheel capture is disabled by default because full mouse tracking can block native terminal text selection and link clicks.

Configuration

Runtime configuration is stored at the extension root:

~/.pi/agent/extensions/pi-sticky-input/config.json

A starter template is included at config/config.example.json. Copy it to config.json for local customization, or let the extension use production defaults when no local config exists.

cp config/config.example.json config.json

The published package intentionally excludes local runtime state: config.json and debug/ stay local to each installation.

Configuration options

| Key | Type | Default | Purpose | |-----|------|---------|---------| | debug | boolean | false | Enables file-only diagnostics under debug/debug.log | | enabled | boolean | true | Enables the extension | | splitFooterRenderer | boolean | true | Enables the sticky split-footer renderer patch | | alternateScreen | boolean | true | Uses an alternate terminal screen while the session is active | | alternateScroll | boolean | false | Lets compatible terminals translate wheel input into alternate-screen cursor sequences | | mouseScroll | boolean | false | Enables SGR mouse-wheel capture for terminals without alternate-scroll support | | mouseWheelScrollRows | number | 3 | Rows scrolled per wheel event | | keyboardScroll | boolean | true | Enables page-key and home/end history scrolling | | keyboardScrollRows | number | 10 | Rows scrolled per keyboard page event | | minimumHistoryRows | number | 3 | Minimum history viewport height before falling back on very small terminals | | historyViewportLineLimit | number | 200 | Maximum retained renderer-managed history lines before choosing the visible slice |

Example config

{
  "debug": false,
  "enabled": true,
  "splitFooterRenderer": true,
  "alternateScreen": true,
  "alternateScroll": false,
  "mouseScroll": false,
  "mouseWheelScrollRows": 3,
  "keyboardScroll": true,
  "keyboardScrollRows": 10,
  "minimumHistoryRows": 3,
  "historyViewportLineLimit": 200
}

Invalid or missing values are normalized to bounded defaults when the extension loads configuration.

Compatibility

• powerline-footer: compatible by default because pi-sticky-input keeps status, widgets, editor, and footer inside the sticky pane instead of replacing singleton editor/footer hooks.
• pi-agent-router: compatible because below-editor widgets remain inside the sticky pane viewport.
• pi-startup-redraw-fix: compatible because pi-sticky-input patches the live TUI.doRender path and uses terminal clear ordering that does not require startup-redraw-fix's full-clear rewrite.
• Overlays and structurally unknown layouts fall back to Pi's original renderer for safety.

Debug logging

Debug logging is disabled by default through "debug": false. When enabled, logs are appended only to:

debug/debug.log

The extension does not write debug output to console, stdout, or stderr, and no debug log file is opened when debug logging is disabled.

Development

npm run typecheck
npm run test
npm run build
npm run package:dry-run

License

MIT © MasuRii