From 4dbf094b65ae696ef359e99037e2a761ae8e0441 Mon Sep 17 00:00:00 2001
From: Mario Zechner <badlogicgames@gmail.com>
Date: Fri, 16 Jan 2026 12:51:09 +0100
Subject: [PATCH] Add PI_NO_HARDWARE_CURSOR env var for terminals with limited
 escape sequence support

Fixes cursor visibility issues in JetBrains IDE terminals (IntelliJ, PyCharm) where
the hardware cursor either blinks or becomes invisible depending on settings.

Fixes #771
---
 packages/coding-agent/README.md | 2 ++
 packages/tui/CHANGELOG.md       | 4 ++++
 packages/tui/src/tui.ts         | 6 ++++++
 3 files changed, 12 insertions(+)

diff --git a/packages/coding-agent/README.md b/packages/coding-agent/README.md
index 76c625ba..60a2d71c 100644
--- a/packages/coding-agent/README.md
+++ b/packages/coding-agent/README.md
@@ -151,6 +151,8 @@ return config
 
 **Windows Terminal:** Does not support the Kitty keyboard protocol. Shift+Enter cannot be distinguished from Enter. Use Ctrl+Enter for multi-line input instead. All other keybindings work correctly.
 
+**IntelliJ IDEA (Integrated Terminal):** The built-in terminal has limited escape sequence support. If you experience cursor visibility issues, set `PI_NO_HARDWARE_CURSOR=1` before running pi. Note that Shift+Enter cannot be distinguished from Enter in IntelliJ's terminal. Consider using a dedicated terminal emulator for the best experience.
+
 ### API Keys & OAuth
 
 **Option 1: Auth file** (recommended)
diff --git a/packages/tui/CHANGELOG.md b/packages/tui/CHANGELOG.md
index 456b6c9d..9730dd2d 100644
--- a/packages/tui/CHANGELOG.md
+++ b/packages/tui/CHANGELOG.md
@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Added
+
+- `PI_NO_HARDWARE_CURSOR=1` environment variable to disable hardware cursor positioning for terminals with limited escape sequence support (e.g., IntelliJ IDEA's built-in terminal)
+
 ## [0.47.0] - 2026-01-16
 
 ### Breaking Changes
diff --git a/packages/tui/src/tui.ts b/packages/tui/src/tui.ts
index 0f550761..d708661f 100644
--- a/packages/tui/src/tui.ts
+++ b/packages/tui/src/tui.ts
@@ -981,6 +981,12 @@ export class TUI extends Container {
 	 * @param totalLines Total number of rendered lines
 	 */
 	private positionHardwareCursor(cursorPos: { row: number; col: number } | null, totalLines: number): void {
+		// PI_NO_HARDWARE_CURSOR=1 disables hardware cursor for terminals that don't handle it well
+		if (process.env.PI_NO_HARDWARE_CURSOR === "1") {
+			this.terminal.hideCursor();
+			return;
+		}
+
 		if (!cursorPos || totalLines <= 0) {
 			this.terminal.hideCursor();
 			return;