mcode-island — 桌面灵动岛状态通知

让用户在不切回 mcode 窗口的情况下，从桌面顶部悬浮 pill 上看到你（agent）的实时工作状态。

What it looks like

A 320×60 pill anchored to the top center of the primary display, always-on-top, dark theme. Six states with distinct color and motion:

Click the pill to switch focus back to the originating terminal tab. Run mcode-island pin from inside a terminal to fix the focus target explicitly (useful when the auto-detected HWND is wrong, e.g. Windows Terminal multi-tab).

When to push each state

Never push the same state twice in a row — the widget de-duplicates by state+message. Push only on transitions, or include a fresh message each time.

Copyable example (agent side)

The plugin ships a thin wrapper wrap-tool.ps1 that publishes state only (it does NOT execute the command). Run the command via mcode's own bash tool, then call wrap-tool.ps1 to publish the outcome:

# Step 1: announce "working" before invoking mcode's bash tool
& "<plugin install dir>\wrap-tool.ps1" -Tool bash -Command "npm test" -Description "run tests"

# Step 2: after mcode's bash tool returns, publish the outcome
& "<plugin install dir>\wrap-tool.ps1" -Tool bash -Command "npm test" -ExitCode $LASTEXITCODE

$LASTEXITCODE is interpreted as: 0 → done, codes in -WaitingExitCodes (default [1]) → waiting, anything else → error. The wrapper returns the exit code unchanged so the calling shell still sees it.

For other tools (read/write/edit) — and for any state push that is not a single command — call notify-island.ps1 directly:

$plugin = "<plugin install dir>"   # directory that contains notify-island.ps1
& "$plugin\notify-island.ps1" -State thinking
& "$plugin\notify-island.ps1" -State working  -Message "read source tree"
& "$plugin\notify-island.ps1" -State done     -Message "indexed 142 files"
& "$plugin\notify-island.ps1" -State error    -Message "compile failed: missing import"
& "$plugin\notify-island.ps1" -State waiting  -Message "permission prompt"

<plugin install dir> is the directory that contains notify-island.ps1. Substitute the absolute path your user installed the plugin at. The Skill body deliberately avoids hard-coded paths so any user / any install location works.

Expected result

After each push, the widget on the user's primary display updates within ~400 ms (one polling cycle). On click, the originating terminal tab regains focus. The widget is intentionally hard to kill: Alt+F4 hides it, not closes it, and mcode-island show re-raises the hidden window in under 1 second.

User-side management

mcode-island                  REM start the widget (idempotent)
mcode-island stop             REM stop the widget
mcode-island status           REM show PID + recent log
mcode-island show             REM re-raise hidden window
mcode-island pin              REM lock focus target to current foreground window
mcode-island unpin            REM clear focus target
mcode-island autostart-on     REM register for Windows logon
mcode-island autostart-off    REM unregister

To enable login auto-start, the user runs once:

& "<plugin install dir>\autostart.ps1" -Enable

This writes to HKCU\Software\Microsoft\Windows\CurrentVersion\Run — no admin rights required.

Runtime data

All widget state lives under %APPDATA%\mcode-island\:

No data leaves the local machine. The plugin does not make any network request.

What is in this package

mcode-island/
├── plugin.json                    # plugin manifest
├── README.md                      # full user-facing docs
├── LICENSE                        # Apache-2.0
├── mcode-island.ps1               # WPF widget main loop
├── mcode-island.cmd               # CLI shim (start/stop/status/...)
├── start-island.ps1               # launch the widget in STA
├── stop-island.ps1                # stop the widget
├── status-island.ps1              # print widget state
├── show-island.ps1                # re-raise hidden widget
├── pin-island.ps1                 # lock focus target to foreground
├── autostart.ps1                  # register/unregister Windows logon
├── notify-island.ps1              # state-push helper (agents call this)
├── wrap-tool.ps1                  # all-in-one bash wrapper
├── skills/mcode-island/SKILL.md   # this file
└── assets/                        # screenshots used in the README

Limitations and known constraints

• Windows 10/11 only (uses WPF and presentationframework).
• Single widget per user session.
• No hover-expand, no media-control integration yet — see the v0.2 roadmap in the upstream issue tracker.
• wrap-tool.ps1 only wraps bash. For read / write / edit the agent must call notify-island.ps1 itself before and after the tool call.