pi-tmux-focus-cursor

Hide Pi's fake editor cursor when the current tmux pane loses focus

Package details

← Back
extension

Install pi-tmux-focus-cursor from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:pi-tmux-focus-cursor
Package
pi-tmux-focus-cursor
Version
0.1.0
Published
Mar 26, 2026
Downloads
34/mo · 10/wk
Author
mauriciojunior
License
MIT
Types
extension
Size
7.9 KB
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-tmux-focus-cursor

Hide Pi’s fake editor cursor whenever the current tmux pane is not focused.

This extension makes Pi feel cleaner inside tmux by removing the inactive fake cursor highlight as soon as focus leaves the pane, then restoring it immediately when focus returns.

Why

Pi renders a fake cursor in its TUI editor. Inside tmux, that can remain visible even when you move to another pane, which makes the inactive Pi pane look like it is still focused.

pi-tmux-focus-cursor fixes that by tracking tmux pane focus and suppressing the fake cursor only while the pane is inactive.

Features

  • Hides Pi’s fake cursor when the tmux pane loses focus
  • Restores the cursor when the pane becomes active again
  • Uses tmux hooks instead of polling
  • Keeps overhead very low
  • Cleans up its tmux hooks on normal shutdown

Requirements

  • Pi
  • tmux
  • tmux focus events enabled:
set -g focus-events on

After changing tmux config, reload or restart tmux.

Installation

Install with npm through Pi:

pi install npm:pi-tmux-focus-cursor

Then start or reload Pi.

How it works

The extension:

  1. detects the current TMUX_PANE
  2. installs tmux pane-focus-in and pane-focus-out hooks for that pane
  3. writes focus state to a temporary state file
  4. updates Pi’s custom editor immediately when that state changes

This avoids polling and makes focus transitions feel effectively instant.

Limitations

  • It tracks tmux pane focus, not arbitrary non-tmux application state.
  • It depends on tmux focus events being available and working correctly in your terminal.
  • If Pi is terminated abruptly, stale tmux hooks may remain until manually cleaned up.

Troubleshooting

It does not react to focus changes

Check that tmux focus events are enabled:

tmux show -gv focus-events

Expected output:

on

If needed, add this to ~/.tmux.conf:

set -g focus-events on

Then restart or reload tmux.

I think old hooks were left behind

Inspect pane hooks:

tmux show-hooks -p -t "$TMUX_PANE"

Development notes

  • index.ts contains the active hook-based implementation

License

MIT