Island

Overview

@nikcli-ai/island (the Swift package under packages/nikcli-island/) ships NikcliIsland.app — a Dynamic-Island-style status HUD that draws over the macOS notch and shows the live state of every nikcli session running on the machine. It is modeled on Pookify (the equivalent for Claude Code), rebuilt around nikcli's own event bus instead of a one-way hook file.

Unlike every other package on the docs site, @nikcli-ai/island is a Swift package — it does not participate in the JS build graph. Its only dependency on nikcli itself is the file contract documented below.

How it works

Three moving parts. The data flows from nikcli's process to the notch UI through a small JSON file contract that the Swift app polls.

1. The bridge. @nikcli-ai/util/island-bridge is started unconditionally from src/index.ts's top-level middleware. It listens on GlobalBus (src/bus/global.ts), which every Bus.publish(...) call already forwards to regardless of mode — so the island reflects any nikcli process running on the machine, not just the TUI.
2. The snapshot file. One JSON file per session under ~/Library/Application Support/NikcliIsland/state.d/, written atomically (temp file + rename). Each snapshot carries the session id, agent title, project, cwd, the writing process's pid, the local server port (when one is running), and a server URL.
3. The Swift app. NikcliIsland.app reads the snapshot directory (port of Pookify's SessionAggregator.swift) and draws the notch (IslandView.swift, NotchWindow.swift, IslandShape.swift, NSScreen+Notch.swift).

Install

Build the Swift package and drop the app into /Applications:

# Inside the nikcli monorepo
      ./packages/nikcli-island/scripts/install.sh

The install.sh script runs swift build -c release, assembles NikcliIsland.app, and installs it to /Applications. An uninstall.sh script is shipped alongside it.

To enable the bridge, start any nikcli command with the --island flag:

nikcli --island
      nikcli tui --island
      nikcli serve --island

The first session activity wakes the app via open -g -b com.nikcli.island; subsequent publishes are no-ops.

State file contract

Each *.json file under ~/Library/Application Support/NikcliIsland/state.d/ is one session's snapshot. The Swift app polls the directory and renders the union. The schema is owned by packages/nikcli-island/Sources/IslandCore/ on the read side and mirrored in src/plugin/island/bridge.ts on the write side.

Beyond the state, each snapshot also carries the parent session id, agent title, project, cwd, the writing process pid, the local server port (when one is running), and a server URL — enough for the native app to invoke POST /permission/:requestID/reply directly when you approve a pending request from the notch.

Permission reply from the notch

The whole reason nikcli's island is more useful than Pookify's is the bidirectional channel. Pookify's hook is one-way: it can render permission.asked, but it has no way to answer it. nikcli's island can, because the writing process is a live nikcli with a real HTTP API and a known server URL.

# What the island POSTs when you tap "Allow" on the notch
curl -X POST http://127.0.0.1:4096/permission/per_example/reply \
  -H "Content-Type: application/json" \
  -d '{"reply":"once"}'

The reply handler is the same one the TUI and mobile composer use; see Permissions for the full request / reply lifecycle.

Disable & rollback

The bridge is opt-in per invocation. To disable the bridge without uninstalling the native app, set the environment variable:

NIKCLI_ISLAND_DISABLE=1 nikcli

Toggling from inside the TUI uses the island feature plugin, which calls IslandBridge.setEnabled(). Turning it off clears the current snapshots and stops writing; turning it back on resumes through the already- registered listener without any race window.

To uninstall the native app entirely:

./packages/nikcli-island/scripts/uninstall.sh

Source anchors