---
slug: "pi-tmux-focus-cursor"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/mauriciojunior/pi-tmux-focus-cursor@main/README.md"
repo: "https://github.com/mauriciojunior/pi-tmux-focus-cursor"
source_file: "README.md"
branch: "main"
---
# 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](https://www.npmjs.com/package/@mariozechner/pi-coding-agent)
- `tmux`
- tmux focus events enabled:

```tmux
set -g focus-events on
```

After changing tmux config, reload or restart tmux.

## Installation

Install with npm through Pi:

```bash
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:

```bash
tmux show -gv focus-events
```

Expected output:

```text
on
```

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

```tmux
set -g focus-events on
```

Then restart or reload tmux.

### I think old hooks were left behind

Inspect pane hooks:

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

## Development notes

- `index.ts` contains the active hook-based implementation

## License

MIT