On macOS the capsule wraps the MacBook notch natively. On Windows it pins to the top-center of the active display. Always above every Space, full-screen app, and virtual desktop.

Highlights

• Native rendering on every platform. WKWebView (Swift) on macOS, WebView2 (C#) on Windows — no Electron, no shipped Chromium, no taskbar entry.
• Notch-aware. On MacBooks with a notch the capsule splits to wrap around it. On other displays it falls back to a single rounded pill.
• One row per pi session. Run pi in five terminals, get five stacked rows in a single capsule.
• Click-through, frameless, always-on-top. Never steals focus, never blocks what's behind it.
• Live config. Type /island in any pi session to change size, screen, or notch behavior without restarting.
• Zero runtime dependencies. The npm package has "dependencies": {}. The native host is the only binary.
• Compile on install. Postinstall builds the host for your platform; missing toolchain is a soft-fail, never a crash.

Platform support

Install

pi install npm:pi-island

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

Toolchain requirements

The postinstall step compiles the native host for your platform.

xcode-select --install

winget install Microsoft.DotNet.SDK.8

If the required toolchain is missing, install still succeeds — the extension simply no-ops and writes a .build-skipped marker. Once you install the toolchain, run:

npm run build

…to compile the host without reinstalling the package.

Settings

Inside any pi session, open the settings panel:

/island

A drop-down opens with four rows. Cycle any row's value with Enter or Space.

Choices persist in ~/.pi/pi-island.json and survive every pi restart.

Quick actions (skip the menu)

For muscle memory and scripts:

/island on            # alias: enable
/island off           # alias: 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 sized to the longest row.

How it works

┌─────────────────────────────────────────────────────────────────────┐
│  pi session  ──►  pi-extension/index.ts                              │
│                       │                                              │
│                       │  per-turn status                             │
│                       ▼                                              │
│                   companion.mjs   ──►   Unix socket / Named pipe     │
│                                                  │                   │
│                                                  ▼                   │
│                                         native host (per OS)         │
│                                         ┌──────────────────┐         │
│                                         │ macOS:  Swift +  │         │
│                                         │         WKWebView│         │
│                                         │ Win:    C#    +  │         │
│                                         │         WebView2 │         │
│                                         └──────────────────┘         │
│                                                  │                   │
│                                                  ▼                   │
│                                         status capsule (HTML/CSS)    │
│                                         pinned, frameless, always   │
│                                         on top, click-through       │
└─────────────────────────────────────────────────────────────────────┘

1. The pi extension (pi-extension/index.ts) hooks every turn and pushes a JSON status frame.
2. A long-lived companion (pi-extension/companion.mjs) owns the IPC channel — Unix domain socket on macOS, named pipe on Windows.
3. A native host renders the capsule from raw HTML/CSS, pinned above every window, click-through and borderless.
4. Multi-session stacking is handled by the companion: every session adds a row; rows fold into a single visual capsule.
5. Notch detection uses safeAreaInsets.top on macOS. On notch-equipped MacBooks the capsule splits around the cutout; otherwise it stays as a single pill.

For a deeper architecture write-up, see AGENT.md.

Troubleshooting

Empty or frozen rows stuck in the capsule

After upgrading while pi was running you may see rows with no project name and a spinner that never advances. Reset the companion:

# Inside any pi session:
/island reload

# Or from a normal shell:
pkill -f pi-island/pi-extension/companion.mjs       # macOS / Linux
taskkill /F /IM "island-host-win.exe"                # Windows

pi-island 0.2.1+ auto-detects and heals a version mismatch on the next /island use, so upgrades from 0.2.1 onward should be silent.

"swiftc not found" or ".NET 8 SDK not found"

Install the toolchain (see Install) and run:

npm run build

Capsule does not appear

Verify the host binary built:

# macOS
ls $(npm root -g)/pi-island/pi-extension/island-host-bin

# Windows
dir "%APPDATA%\npm\node_modules\pi-island\pi-extension\hosts\windows"

If missing, run npm run build from the package directory.

Configuration file

Settings live at ~/.pi/pi-island.json:

{
  "enabled": true,
  "size": "medium",
  "screen": "primary",
  "notchWrap": "auto"
}

Edit it directly if you prefer — companion picks up changes on the next status frame.

Project layout

pi-island/
├── pi-extension/        Extension entry, companion, platform abstraction
│   ├── index.ts         Hooks pi turns, streams status frames
│   ├── companion.mjs    Long-lived IPC + host process owner
│   └── platform.mjs     OS-specific screen, geometry, notch logic
├── hosts/
│   ├── macos/           Swift + WKWebView source
│   └── windows/         C# + WinForms + WebView2 source
├── scripts/
│   ├── build.mjs        Per-platform build dispatcher
│   ├── postinstall.mjs  Compile-on-install with graceful fallback
│   └── pack-test.mjs    Pre-publish smoke test
├── docs/RELEASING.md    Three-loop dev/release workflow
├── web/                 Next.js 16 informational site (pi-island.vercel.app)
└── AGENT.md             Architecture notes & contributor docs

Development

The dev/release workflow is documented in docs/RELEASING.md. Highlights:

• npm run dev:link — symlink the global pi-island to this repo for live edits
• npm run pack:test — produce the exact tarball npm publish would upload, install it globally, and run real pi flows against it
• npm run release:patch / :minor / :major — bump, commit, tag, push (CI publishes to npm)
• npm run release:beta — bump to a -beta.N pre-release; CI routes it to the beta npm dist-tag

Architecture notes for contributors live in AGENT.md.

Roadmap

• macOS host (Swift + WKWebView)
• Windows host (C# + WinForms + WebView2)
• Linux host — #6
• Custom themes / per-row color
• Optional click-through toggle (interactive mode)

Contributing

Issues and PRs welcome. Before submitting a PR:

1. Read AGENT.md for architecture conventions.
2. Read docs/RELEASING.md — dev mode is npm run dev:link.
3. Keep PR scope tight; pre-1.0 we accept breaking changes in minor bumps but document them in the release notes.

License

MIT © phun333

Built on top of pi, the open-source coding agent by badlogic.