https://github.com/phun333/pi-island
Windows and macOS Dynamic Island for the pi coding agent — see what pi is doing, pinned to the top of your screen
https://github.com/phun333/pi-island
agent-ui dynamic-island macos notch pi-coding-agent pi-extension pi-package status-bar webkit windows wkwebview
Last synced: 1 day ago
JSON representation
Windows and macOS Dynamic Island for the pi coding agent — see what pi is doing, pinned to the top of your screen
- Host: GitHub
- URL: https://github.com/phun333/pi-island
- Owner: phun333
- License: mit
- Created: 2026-04-20T14:48:52.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-04-28T15:52:09.000Z (about 1 month ago)
- Last Synced: 2026-05-29T00:06:23.568Z (3 days ago)
- Topics: agent-ui, dynamic-island, macos, notch, pi-coding-agent, pi-extension, pi-package, status-bar, webkit, windows, wkwebview
- Language: Swift
- Homepage: https://pi-island.vercel.app
- Size: 1.09 MB
- Stars: 24
- Watchers: 0
- Forks: 4
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# pi-island
**A Dynamic-Island-style status capsule for the [pi coding agent](https://github.com/badlogic/pi-mono).**
Native, pinned to the top of your screen, live on every turn.
[](https://www.npmjs.com/package/pi-island)
[](https://www.npmjs.com/package/pi-island)
[](LICENSE)
[](package.json)
[](#platform-support)
[](https://github.com/phun333/pi-island/actions/workflows/publish.yml)
[](https://github.com/phun333/pi-island/stargazers)
[Website](https://pi-island.vercel.app) · [Install](#install) · [Settings](#settings) · [How it works](#how-it-works) · [Troubleshooting](#troubleshooting)
---
> 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
| OS | Host | Toolchain | Notch wrap |
|---------|---------------------------------------|-----------------------------------------------|------------|
| macOS | Swift + WKWebView | Xcode Command Line Tools (`swiftc`) | Yes |
| Windows | C# + WinForms + WebView2 | .NET 8 SDK (`dotnet`) | N/A |
| Linux | _Tracked in [#6](https://github.com/phun333/pi-island/issues/6)_ | — | — |
## Install
```bash
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.
macOS — Xcode Command Line Tools
```bash
xcode-select --install
```
Windows — .NET 8 SDK
```powershell
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:
```bash
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**.
| Setting | Values | Notes |
|-------------|----------------------------------------------|------------------------------------------------------------------------------------------------|
| Visibility | `enabled` · `disabled` | Remembered across restarts. |
| Size | `small` · `medium` · `large` · `xlarge` | Live — no respawn. |
| Screen | `primary` · `active` · `2` · `3` … | `primary` = menu-bar display, `active` = under the mouse, numbers for multi-monitor. |
| Notch wrap | `auto` · `normal` · `notch` | macOS only. `auto` detects automatically; you can also force on/off. Inert on Windows. |
Choices persist in `~/.pi/pi-island.json` and survive every pi restart.
### Quick actions (skip the menu)
For muscle memory and scripts:
```bash
/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`](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:
```bash
# 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](#install)) and run:
```bash
npm run build
```
### Capsule does not appear
Verify the host binary built:
```bash
# 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`:
```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`](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`](AGENT.md).
## Roadmap
- [x] macOS host (Swift + WKWebView)
- [x] Windows host (C# + WinForms + WebView2)
- [ ] Linux host — [#6](https://github.com/phun333/pi-island/issues/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`](AGENT.md) for architecture conventions.
2. Read [`docs/RELEASING.md`](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](LICENSE) © [phun333](https://github.com/phun333)
Built on top of [pi](https://pi.dev), the open-source coding agent by [badlogic](https://github.com/badlogic/pi-mono).