pi-startup-redraw-fix

Pi extension that patches terminal full-clear ordering to avoid startup redraw glitches.

Package details

← Back
extension

Install pi-startup-redraw-fix from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:pi-startup-redraw-fix
Package
pi-startup-redraw-fix
Version
0.1.9
Published
Apr 25, 2026
Downloads
373/mo · 191/wk
Author
masurii
License
MIT
Types
extension
Size
1.4 MB
Dependencies
0 dependencies · 2 peers
Pi manifest JSON
{
  "extensions": [
    "./index.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-startup-redraw-fix

A Pi coding agent extension that patches terminal full-clear escape sequence ordering to prevent startup redraw glitches in certain terminal emulators.

Table of Contents

Features

  • Escape Sequence Normalization — Reorders the startup full-clear sequence from \x1b[3J\x1b[2J\x1b[H to \x1b[H\x1b[2J\x1b[3J for stable screen clearing
  • Idempotent Patching — Applies the patch once per Node process via ProcessTerminal.prototype.write monkey-patching with internal flag guard
  • Failure Notifications — Displays a UI warning on session_start if the patch failed to apply

Installation

Extension Folder (Recommended)

Place the extension folder in one of Pi's auto-discovered extension locations:

Location Path
Global default ~/.pi/agent/extensions/pi-startup-redraw-fix (respects PI_CODING_AGENT_DIR)
Project .pi/extensions/pi-startup-redraw-fix

Alternatively, add the path to your Pi settings extensions array.

npm Package

pi install npm:pi-startup-redraw-fix

Git Repository

pi install git:github.com/MasuRii/pi-startup-redraw-fix

Usage

This extension operates automatically with no commands required.

When loaded, the extension immediately patches ProcessTerminal.prototype.write to intercept and normalize terminal clear sequences. If the patch fails, a warning notification appears at each session start (when UI is available).

Configuration

Configuration is stored at config.json alongside the extension:

Default global path: ~/.pi/agent/extensions/pi-startup-redraw-fix/config.json
Actual global path: $PI_CODING_AGENT_DIR/extensions/pi-startup-redraw-fix/config.json when PI_CODING_AGENT_DIR is set

A template is provided at config/config.example.json.

Options

Option Type Default Description
enabled boolean true Enable or disable the extension

Example Configuration

{
  "enabled": true
}

Note: If your Pi build does not honor the enabled flag, disable the extension by removing it from your Pi settings extensions list or uninstalling it.

Technical Details

How It Works

Pi's TUI uses @mariozechner/pi-tui's ProcessTerminal class to write escape sequences to the terminal. This extension wraps ProcessTerminal.prototype.write to normalize the clear sequence order:

Original Sequence Fixed Sequence
ESC[3J (clear scrollback) ESC[H (cursor home)
ESC[2J (clear screen) ESC[2J (clear screen)
ESC[H (cursor home) ESC[3J (clear scrollback)

The reordering ensures the cursor moves home before clearing, which resolves redraw glitches on certain terminal emulators.

Architecture

File Purpose
index.ts Root entrypoint for Pi auto-discovery
src/index.ts Extension bootstrap and session warning handler
src/terminal-clear-patch.ts Monkey-patch implementation with idempotency guard
src/normalize-clear-sequence.ts String replacement utility
src/constants.ts Escape sequence definitions

Limitations

  • Only affects data written via ProcessTerminal.prototype.write
  • Only rewrites the exact byte sequence \x1b[3J\x1b[2J\x1b[H
  • Will not help if redraw issues are caused by different escape sequences
  • Patch fails if ProcessTerminal.write is unavailable or the API changes

Troubleshooting

Warning: "failed to patch terminal clear sequence …"

This warning appears on session_start when the extension cannot patch ProcessTerminal.prototype.write.

Possible Causes:

  • Incompatible Pi or @mariozechner/pi-tui version where ProcessTerminal.write is missing or changed
  • Another extension modified the terminal layer unexpectedly

Solutions:

  1. Update Pi and all extensions to latest versions
  2. Temporarily disable other terminal/TUI-related extensions to identify conflicts
  3. Verify the extension is loaded from an auto-discovery folder or referenced in Pi settings

Development

# Build TypeScript
npm run build

# Run linter
npm run lint

# Run tests
npm run test

# Run all checks
npm run check

Requirements

  • Node.js ≥ 20
  • Peer dependencies: @mariozechner/pi-coding-agent, @mariozechner/pi-tui

Related Pi Extensions

License

MIT