{"id":50394427,"url":"https://github.com/phun333/pi-island","last_synced_at":"2026-05-30T20:02:39.254Z","repository":{"id":352674300,"uuid":"1216082712","full_name":"phun333/pi-island","owner":"phun333","description":"Windows and macOS Dynamic Island for the pi coding agent — see what pi is doing, pinned to the top of your screen","archived":false,"fork":false,"pushed_at":"2026-04-28T15:52:09.000Z","size":1147,"stargazers_count":24,"open_issues_count":2,"forks_count":4,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-29T00:06:23.568Z","etag":null,"topics":["agent-ui","dynamic-island","macos","notch","pi-coding-agent","pi-extension","pi-package","status-bar","webkit","windows","wkwebview"],"latest_commit_sha":null,"homepage":"https://pi-island.vercel.app","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/phun333.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-20T14:48:52.000Z","updated_at":"2026-05-28T05:09:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/phun333/pi-island","commit_stats":null,"previous_names":["phun333/pi-island"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/phun333/pi-island","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phun333%2Fpi-island","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phun333%2Fpi-island/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phun333%2Fpi-island/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phun333%2Fpi-island/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/phun333","download_url":"https://codeload.github.com/phun333/pi-island/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phun333%2Fpi-island/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33707328,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-ui","dynamic-island","macos","notch","pi-coding-agent","pi-extension","pi-package","status-bar","webkit","windows","wkwebview"],"created_at":"2026-05-30T20:02:37.220Z","updated_at":"2026-05-30T20:02:39.248Z","avatar_url":"https://github.com/phun333.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# pi-island\n\n**A Dynamic-Island-style status capsule for the [pi coding agent](https://github.com/badlogic/pi-mono).**\nNative, pinned to the top of your screen, live on every turn.\n\n[![npm version](https://img.shields.io/npm/v/pi-island?style=flat-square\u0026color=333\u0026label=npm)](https://www.npmjs.com/package/pi-island)\n[![npm downloads](https://img.shields.io/npm/dw/pi-island?style=flat-square\u0026color=33\u0026label=downloads)](https://www.npmjs.com/package/pi-island)\n[![License: MIT](https://img.shields.io/npm/l/pi-island?style=flat-square\u0026color=333)](LICENSE)\n[![Node ≥ 18](https://img.shields.io/node/v/pi-island?style=flat-square\u0026color=333)](package.json)\n[![Platforms](https://img.shields.io/badge/platform-macOS%20%7C%20Windows-333?style=flat-square)](#platform-support)\n[![CI](https://img.shields.io/github/actions/workflow/status/phun333/pi-island/publish.yml?style=flat-square\u0026color=333\u0026label=ci)](https://github.com/phun333/pi-island/actions/workflows/publish.yml)\n[![GitHub stars](https://img.shields.io/github/stars/phun333/pi-island?style=flat-square\u0026color=333)](https://github.com/phun333/pi-island/stargazers)\n\n[Website](https://pi-island.vercel.app) · [Install](#install) · [Settings](#settings) · [How it works](#how-it-works) · [Troubleshooting](#troubleshooting)\n\n\u003c/div\u003e\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n\u003cvideo src=\"https://github.com/user-attachments/assets/db5cd9a6-d949-4094-800e-e7aa36c143a3\" controls muted autoplay playsinline width=\"720\"\u003e\u003c/video\u003e\n\n\u003c/div\u003e\n\n\u003e On **macOS** the capsule wraps the MacBook notch natively.\n\u003e On **Windows** it pins to the top-center of the active display.\n\u003e Always above every Space, full-screen app, and virtual desktop.\n\n---\n\n## Highlights\n\n- **Native rendering on every platform.** WKWebView (Swift) on macOS, WebView2 (C#) on Windows — no Electron, no shipped Chromium, no taskbar entry.\n- **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.\n- **One row per pi session.** Run pi in five terminals, get five stacked rows in a single capsule.\n- **Click-through, frameless, always-on-top.** Never steals focus, never blocks what's behind it.\n- **Live config.** Type `/island` in any pi session to change size, screen, or notch behavior without restarting.\n- **Zero runtime dependencies.** The npm package has `\"dependencies\": {}`. The native host is the only binary.\n- **Compile on install.** Postinstall builds the host for your platform; missing toolchain is a soft-fail, never a crash.\n\n## Platform support\n\n| OS      | Host                                  | Toolchain                                     | Notch wrap |\n|---------|---------------------------------------|-----------------------------------------------|------------|\n| macOS   | Swift + WKWebView                     | Xcode Command Line Tools (`swiftc`)           | Yes        |\n| Windows | C# + WinForms + WebView2              | .NET 8 SDK (`dotnet`)                         | N/A        |\n| Linux   | _Tracked in [#6](https://github.com/phun333/pi-island/issues/6)_ | —                | —          |\n\n## Install\n\n```bash\npi install npm:pi-island\n```\n\nThat's it. The island turns on automatically for every pi session after install. Type `/island` any time to tweak it.\n\n### Toolchain requirements\n\nThe postinstall step compiles the native host for your platform.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003emacOS\u003c/strong\u003e — Xcode Command Line Tools\u003c/summary\u003e\n\n```bash\nxcode-select --install\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eWindows\u003c/strong\u003e — .NET 8 SDK\u003c/summary\u003e\n\n```powershell\nwinget install Microsoft.DotNet.SDK.8\n```\n\u003c/details\u003e\n\nIf 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:\n\n```bash\nnpm run build\n```\n\n…to compile the host without reinstalling the package.\n\n## Settings\n\nInside any pi session, open the settings panel:\n\n```\n/island\n```\n\nA drop-down opens with four rows. Cycle any row's value with **Enter** or **Space**.\n\n| Setting     | Values                                       | Notes                                                                                          |\n|-------------|----------------------------------------------|------------------------------------------------------------------------------------------------|\n| Visibility  | `enabled` \u0026middot; `disabled`                | Remembered across restarts.                                                                    |\n| Size        | `small` \u0026middot; `medium` \u0026middot; `large` \u0026middot; `xlarge` | Live — no respawn.                                                                  |\n| Screen      | `primary` \u0026middot; `active` \u0026middot; `2` \u0026middot; `3` … | `primary` = menu-bar display, `active` = under the mouse, numbers for multi-monitor.    |\n| Notch wrap  | `auto` \u0026middot; `normal` \u0026middot; `notch`    | macOS only. `auto` detects automatically; you can also force on/off. Inert on Windows.         |\n\nChoices persist in `~/.pi/pi-island.json` and survive every pi restart.\n\n### Quick actions (skip the menu)\n\nFor muscle memory and scripts:\n\n```bash\n/island on            # alias: enable\n/island off           # alias: disable\n/island toggle\n/island size large\n/island screen primary\n/island notch notch\n/island reload        # reset companion state (emergency eject)\n```\n\nRun pi in multiple terminals — each session gets its own row, stacked into one continuous capsule sized to the longest row.\n\n## How it works\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│  pi session  ──►  pi-extension/index.ts                              │\n│                       │                                              │\n│                       │  per-turn status                             │\n│                       ▼                                              │\n│                   companion.mjs   ──►   Unix socket / Named pipe     │\n│                                                  │                   │\n│                                                  ▼                   │\n│                                         native host (per OS)         │\n│                                         ┌──────────────────┐         │\n│                                         │ macOS:  Swift +  │         │\n│                                         │         WKWebView│         │\n│                                         │ Win:    C#    +  │         │\n│                                         │         WebView2 │         │\n│                                         └──────────────────┘         │\n│                                                  │                   │\n│                                                  ▼                   │\n│                                         status capsule (HTML/CSS)    │\n│                                         pinned, frameless, always   │\n│                                         on top, click-through       │\n└─────────────────────────────────────────────────────────────────────┘\n```\n\n1. **The pi extension** (`pi-extension/index.ts`) hooks every turn and pushes a JSON status frame.\n2. **A long-lived companion** (`pi-extension/companion.mjs`) owns the IPC channel — Unix domain socket on macOS, named pipe on Windows.\n3. **A native host** renders the capsule from raw HTML/CSS, pinned above every window, click-through and borderless.\n4. **Multi-session stacking** is handled by the companion: every session adds a row; rows fold into a single visual capsule.\n5. **Notch detection** uses `safeAreaInsets.top` on macOS. On notch-equipped MacBooks the capsule splits around the cutout; otherwise it stays as a single pill.\n\nFor a deeper architecture write-up, see [`AGENT.md`](AGENT.md).\n\n## Troubleshooting\n\n### Empty or frozen rows stuck in the capsule\n\nAfter upgrading while pi was running you may see rows with no project name and a spinner that never advances. Reset the companion:\n\n```bash\n# Inside any pi session:\n/island reload\n\n# Or from a normal shell:\npkill -f pi-island/pi-extension/companion.mjs       # macOS / Linux\ntaskkill /F /IM \"island-host-win.exe\"                # Windows\n```\n\npi-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.\n\n### \"swiftc not found\" or \".NET 8 SDK not found\"\n\nInstall the toolchain (see [Install](#install)) and run:\n\n```bash\nnpm run build\n```\n\n### Capsule does not appear\n\nVerify the host binary built:\n\n```bash\n# macOS\nls $(npm root -g)/pi-island/pi-extension/island-host-bin\n\n# Windows\ndir \"%APPDATA%\\npm\\node_modules\\pi-island\\pi-extension\\hosts\\windows\"\n```\n\nIf missing, run `npm run build` from the package directory.\n\n## Configuration file\n\nSettings live at `~/.pi/pi-island.json`:\n\n```json\n{\n  \"enabled\": true,\n  \"size\": \"medium\",\n  \"screen\": \"primary\",\n  \"notchWrap\": \"auto\"\n}\n```\n\nEdit it directly if you prefer — companion picks up changes on the next status frame.\n\n## Project layout\n\n```\npi-island/\n├── pi-extension/        Extension entry, companion, platform abstraction\n│   ├── index.ts         Hooks pi turns, streams status frames\n│   ├── companion.mjs    Long-lived IPC + host process owner\n│   └── platform.mjs     OS-specific screen, geometry, notch logic\n├── hosts/\n│   ├── macos/           Swift + WKWebView source\n│   └── windows/         C# + WinForms + WebView2 source\n├── scripts/\n│   ├── build.mjs        Per-platform build dispatcher\n│   ├── postinstall.mjs  Compile-on-install with graceful fallback\n│   └── pack-test.mjs    Pre-publish smoke test\n├── docs/RELEASING.md    Three-loop dev/release workflow\n├── web/                 Next.js 16 informational site (pi-island.vercel.app)\n└── AGENT.md             Architecture notes \u0026 contributor docs\n```\n\n## Development\n\nThe dev/release workflow is documented in [`docs/RELEASING.md`](docs/RELEASING.md). Highlights:\n\n- `npm run dev:link` — symlink the global `pi-island` to this repo for live edits\n- `npm run pack:test` — produce the exact tarball `npm publish` would upload, install it globally, and run real pi flows against it\n- `npm run release:patch` / `:minor` / `:major` — bump, commit, tag, push (CI publishes to npm)\n- `npm run release:beta` — bump to a `-beta.N` pre-release; CI routes it to the `beta` npm dist-tag\n\nArchitecture notes for contributors live in [`AGENT.md`](AGENT.md).\n\n## Roadmap\n\n- [x] macOS host (Swift + WKWebView)\n- [x] Windows host (C# + WinForms + WebView2)\n- [ ] Linux host — [#6](https://github.com/phun333/pi-island/issues/6)\n- [ ] Custom themes / per-row color\n- [ ] Optional click-through toggle (interactive mode)\n\n## Contributing\n\nIssues and PRs welcome. Before submitting a PR:\n\n1. Read [`AGENT.md`](AGENT.md) for architecture conventions.\n2. Read [`docs/RELEASING.md`](docs/RELEASING.md) — dev mode is `npm run dev:link`.\n3. Keep PR scope tight; pre-1.0 we accept breaking changes in `minor` bumps but document them in the release notes.\n\n## License\n\n[MIT](LICENSE) © [phun333](https://github.com/phun333)\n\nBuilt on top of [pi](https://pi.dev), the open-source coding agent by [badlogic](https://github.com/badlogic/pi-mono).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphun333%2Fpi-island","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphun333%2Fpi-island","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphun333%2Fpi-island/lists"}