# pi-editor-cursor

[![npm version](https://badgen.net/npm/v/pi-editor-cursor)](https://www.npmjs.com/package/pi-editor-cursor) [![npm downloads](https://badgen.net/npm/dm/pi-editor-cursor)](https://www.npmjs.com/package/pi-editor-cursor) [![license](https://badgen.net/npm/license/pi-editor-cursor)](LICENSE)

A small [Pi coding agent](https://github.com/earendil-works/pi) package that replaces the input editor cursor with a slow blinking symbol and prefixes the editor with `>: `.

While Pi is working, the cursor becomes a static dim symbol.

| Light | Dark |
|:---:|:---:|
| ![Light theme cursor](assets/cursor.gif) | ![Dark theme cursor](assets/cursor-dark.gif) |

## Installation

Install the package globally:

```bash
pi install npm:pi-editor-cursor
```

The extension loads automatically and works with its defaults. For a project-local installation, add `-l`:

```bash
pi install -l npm:pi-editor-cursor
```

## Configuration

Create `~/.pi/agent/editor-cursor.json` (or `editor-cursor.json` in the directory selected by `PI_CODING_AGENT_DIR`):

```json
{
  "blinkMs": 700,
  "prompt": ">: ",
  "symbol": "█",
  "color": "accent",
  "working": {
    "symbol": "░"
  }
}
```

These are the complete supported settings:

- `blinkMs` — idle blink interval in milliseconds. Set `0` for a permanently visible idle cursor.
- `prompt` — one-line editor prefix, at most 24 characters.
- `symbol` — exactly one terminal-cell-wide Unicode code point used for the idle cursor.
- `color` — a Pi theme color name or `#rrggbb`.
- `working.symbol` — exactly one terminal-cell-wide Unicode code point used while the agent is working; it is rendered dim and does not blink.

Missing or invalid fields use their defaults. Named colors are validated against the active theme at startup; unknown names fall back to `accent`. The file is not watched: edit it, then restart Pi or use Pi's manual `/reload` command to reload the extension and configuration in the current session.

## Compatibility and recovery

This package depends on Pi's custom-editor extension API, a private and unstable renderer hook. It was developed against Pi `0.80.10` on Node `24.18.0`.

At startup it verifies the editor API and cursor-rendering protocol before replacing the editor. If a check or installation fails, it restores the stock editor while it still owns the replacement and shows one concise warning. A pre-existing or later custom editor is left untouched.

To disable the package, remove it and restart Pi:

```bash
pi remove npm:pi-editor-cursor
```

If Pi fails before the extension warning is visible, remove the package entry from `~/.pi/agent/settings.json` (or `.pi/settings.json` for a project-local (`-l`) install), then restart Pi.

## Development

```bash
pnpm install
pnpm run check
pnpm run pack:dry
```

## License

[MIT](LICENSE)