Mcode Island

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).

Two ways to drive the pill

Mode A — Hook-driven (mcode 0.2.4+ with io.minimax.mcode)

When mcode accepts the io.minimax.mcode client extension, the runtime spawns the script under io.minimax.mcode/hooks/scripts/<event>.ps1 for every matching lifecycle event. The agent does not need to push state manually.

The hooks conform to the portable spec proposed in MiniMax-Code-Plugins PR #20. Each script reads the JSON event payload from stdin, calls notify-island.ps1 with the appropriate state, and exits 0 (decision-bearing events also write a JSON decision to stdout). Self-push filtering prevents the pill from churning when the agent calls notify-island.ps1 directly through Bash.

If you are running on mcode 0.2.4+ and the pill is updating itself before you push anything, Mode A is active. Otherwise fall through to Mode B.

Mode B — Agent-pushed (legacy, always works)

For older mcode, or when the io.minimax.mcode extension is not yet active (registry validator has not accepted the namespace), the agent pushes state through notify-island.ps1 directly. The mcode-status-detect.ps1 detector also infers state from the runtime's ledger.jsonl / messages.jsonl, so the pill will still move — your manual pushes just sharpen the message and cover edge cases (notably ask_user).

ask_user is a special tool — the detector cannot infer it is a "wait for user" moment (it looks like any other tool call to the session log). When in Mode B, the agent MUST push waiting immediately before invoking ask_user, and done immediately after the user answers; otherwise the pill will sit in working (yellow/blue) while the user is actually being asked to decide. In Mode A, the same coverage comes for free because ask_user is a tool call that fires PreToolUse/PostToolUse.

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, Mode B)

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.

The wrapper accepts -Tool bash|read|write|edit|glob|grep|web|task|notebook and emits a tool-specific done message (e.g. read C:\path, edited file.cs, npm test 完成) so the pill text is informative. For read/write/edit/glob/grep the wrapper itself does not execute the command — mcode's own tool does; this script only publishes the state.

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 (or after each hook fires), 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 widget
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 unless an opt-in 5-hour usage token is configured. See the Network access + Accounts sections in README.md for the exact host (api.minimax.io/v1/coding_plan/remains), the rate limit (one GET per 60 s), and the storage locations (config.json:planApiToken or env MINIMAX_OAUTH_TOKEN / MINIMAX_API_KEY). When no token is configured the plugin makes no network requests at all.

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
├── mcode-status-detect.ps1           # runtime-state detector
├── io.minimax.mcode/                 # client extension (PR #20 spec)
│   └── hooks/
│       ├── hooks.json                # 12-event declaration
│       └── scripts/
│           ├── _lib.ps1              # shared helper
│           ├── session-start.ps1
│           ├── session-end.ps1
│           ├── user-prompt-submit.ps1
│           ├── pre-tool-use.ps1
│           ├── post-tool-use.ps1
│           ├── stop.ps1
│           ├── pre-compact.ps1
│           ├── notification.ps1
│           ├── subagent-start.ps1
│           ├── subagent-stop.ps1
│           ├── permission-request.ps1
│           └── permission-denied.ps1
├── skills/mcode-island/SKILL.md      # this file
└── assets/                           # screenshots used in the README

Limitations and known constraints

• Windows 10/11 only (uses WPF, user32, and kernel32 P/Invoke).
• Single widget per user session.
• Hook-driven mode requires mcode 0.2.4+ Runtime. The portable spec (io.minimax.mcode client extension) is still pending merge in MiniMax-Code-Plugins PR #20; until the registry validator accepts the namespace, the hooks subdirectory is dormant and the plugin falls back to Mode B (agent-pushed + detector).
• No hover-expand, no media-control integration yet — see the v0.2 roadmap in the upstream issue tracker.
• wrap-tool.ps1 is a status publisher only — it never executes the command itself (mcode's tool does). The agent still runs every read / write / edit through mcode and then calls wrap-tool.ps1 to publish the outcome. This avoids shell-injection ambiguity from a prior Invoke-Expression design.