pi-island

Dynamic-Island-style status capsule for the pi coding agent on macOS and Windows. Shows what pi is doing in real time, at the very top of your screen — with native notch-wrap support for MacBooks.

Package details

← Back

extension

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

npm repo home report

$ pi install npm:pi-island

Package: pi-island
Version: 0.3.0
Published: Apr 24, 2026
Downloads: 1,127/mo · 538/wk
Author: phun333
License: MIT
Types: extension
Size: 168.6 KB
Dependencies: 0 dependencies · 2 peers

Pi manifest JSON

{
  "extensions": [
    "./pi-extension/index.ts"
  ]
}

Security note

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

README

pi-island

A Dynamic-Island-style status capsule for the pi coding agent. Pinned at the top of your screen on macOS and Windows, live on every turn.

On macOS the capsule wraps the MacBook notch natively. On Windows it pins to the top-center of the active display.

Install

Supported on macOS and Windows. You need pi plus the toolchain for your platform:

macOS — Xcode Command Line Tools (xcode-select --install)
Windows — .NET 8 SDK (winget install Microsoft.DotNet.SDK.8)

Then:

pi install npm:pi-island

The postinstall step compiles the native host for your platform (Swift on macOS, C# / WebView2 on Windows). If the required toolchain is missing, the install still succeeds — the extension just no-ops until you install it and run npm run build.

The island turns on automatically for every pi session after install. Type /island any time to tweak it.

Settings

Inside any pi session, type:

/island

A drop-down opens with four rows. Cycle each value with Enter or Space:

Setting	Values	Notes
Visibility	`enabled` / `disabled`	Remember the choice across restarts.
Size	`small` / `medium` / `large` / `xlarge`	Live — no respawn.
Screen	`primary` / `active` / `2` / `3` …	`primary` = menu-bar display, `active` = under mouse, numbers for multi-monitor.
Notch wrap	`auto` / `normal` / `notch`	macOS only. `auto` detects; forcing off/on also supported. On Windows this row is inert.

Your choices are persisted in ~/.pi/pi-island.json and survive every pi restart.

Quick-actions (skip the menu)

Muscle memory / scripts:

/island on            # or: enable
/island off           # or: disable
/island toggle
/island size large
/island screen primary
/island notch notch
/island reload        # reset companion state (emergency eject)

Run pi in multiple terminals — each session gets its own row, stacked into one continuous capsule.

Troubleshooting

Empty / frozen rows stuck in the capsule

If you see rows with no project name and a spinner that never advances (typically after upgrading pi-island while pi was running), reset the companion in one of two ways:

Inside pi: /island reload — nukes state in place.

Outside pi:

pkill -f pi-island/pi-extension/companion.mjs

Either one is a one-shot cleanup. pi-island 0.2.1+ auto-detects and heals a version mismatch on the next /island use, so upgrading from 0.2.1 onward should be silent.

Website

A minimal informational site lives in web/ — built with Next.js 16 and the pi.dev palette, deployable to Vercel with Root Directory = web. See web/README.md.

Development

Dev/release workflow (link, pack-test, publish) is documented in docs/RELEASING.md.

License

MIT — see LICENSE. Architecture notes & contributor docs live in AGENT.md.