pi-clear-hotkey

This pi extension clears the terminal viewport from a keyboard shortcut, Ctrl+L by default. The session, its context, and the terminal scrollback stay as they are.

pi holds the terminal in raw mode, so Ctrl+L never reaches the shell. The editor swallows the unbound control character instead. pi has no clear-screen action to bind either: app.clear clears the editor text, and app.session.new starts a new session and drops the conversation.

The clear runs inside the TUI. ctx.ui.setEditorComponent wraps the prompt editor and hands it the live TUI object, so the handler calls tui.terminal.clearScreen() and then tui.renderNow(true). The forced render resets pi's differential renderer. Without it, the renderer keeps diffing against a frame that is no longer on screen.

The prompt editor handles the key, and nothing else does. The extension never calls pi.registerShortcut(), so pi reports no shortcut conflict at startup and every picker keeps its own bindings. For example, Ctrl+L still filters labeled entries in the session tree.

Install

The extension needs pi in interactive TUI mode and Node.js 22.18 or newer. It is tested against pi 0.84.4. The editor factory it uses landed in pi 0.70.6.

Install from npm, which is the recommended method. The package is @jetserge/pi-clear-hotkey:

pi install npm:@jetserge/pi-clear-hotkey

Run it without installing:

pi -e npm:@jetserge/pi-clear-hotkey

Installing from source also works, and tracks main rather than a release:

pi install git:github.com/CrazyCoder/pi-clear-hotkey

After installation, restart pi or run /reload.

When the key is already taken

pi binds Ctrl+L to app.model.select out of the box. The wrapped editor sees the key first, so the hotkey works immediately. The model selector then stops opening from Ctrl+L while the prompt editor has focus.

To keep the model selector where it is, pick another clear key in the config below. To keep the clear key on Ctrl+L, move the model selector in ~/.pi/agent/keybindings.json:

{
	"app.model.select": "ctrl+p",
	"app.model.cycleForward": "alt+p",
	"app.model.cycleBackward": ["shift+alt+p", "ctrl+alt+p"]
}

Picker bindings are not affected either way, because each picker handles its own input.

Configuration

The config file is optional. Without it, the extension binds Ctrl+L. The extension reads ~/.pi/agent/pi-clear-hotkey.json, or $PI_CODING_AGENT_DIR/pi-clear-hotkey.json when that variable is set.

{
	"key": "alt+k"
}

key is the only field. It takes pi's own key format: any number of ctrl, shift, alt, and super prefixes, then the base key, joined by +. Examples: ctrl+l, alt+k, shift+alt+c, ctrl++.

The extension reports an invalid key on session start and binds Ctrl+L instead. Set key to "" to bind nothing:

{
	"key": ""
}

/clear-screen clears the viewport from the command line, the same as the hotkey. It works even when key is empty.

shift+ctrl+* and shift+alt+* need a terminal that speaks the Kitty keyboard protocol or modifyOtherKeys. Windows Terminal sends the legacy sequence instead, and pi does not match that sequence.

What it does not do

The extension clears the visible viewport only. Terminal scrollback survives, so Ctrl+Shift+Up and the scroll wheel still reach earlier output.

Nothing about the session changes: no new session, no context reset, no compaction. The next message continues the same conversation.

The key is inert outside the prompt editor. In a picker or an overlay, pi's own binding for that key applies.

/hotkeys lists pi's keybindings and the shortcuts extensions register through pi.registerShortcut(). This extension registers neither, so the key does not appear there.

For a clear on launch and on /new rather than a hotkey, see @janvitos/pi-clear-screen. The two extensions do not conflict.

Development

npm install
npm run check    # tsc --noEmit, then the test suite

@earendil-works/pi-coding-agent and @earendil-works/pi-tui are peer dependencies. The pi process supplies them at runtime, and they install as devDependencies for the typecheck. The package adds no runtime dependencies of its own.

Load the working copy directly:

pi -e ./index.ts

License

MIT