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: | state | color | icon | meaning | | ---------- | -------------- | ---- | -------------------------------- | | `idle` | gray | — | waiting for user input | | `thinking` | yellow pulse | — | reasoning, no tool call yet | | `working` | blue pulse | ⚙ | actively running a tool | | `waiting` | orange | ? | tool needs user approval / input | | `done` | green | ✓ | step finished, more to do | | `error` | red | ✕ | tool or step failed | 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. | event | script | pill state | | ----------------- | --------------------------------- | ----------- | | `SessionStart` | `session-start.ps1` | `idle` | | `SessionEnd` | `session-end.ps1` | `idle` | | `UserPromptSubmit`| `user-prompt-submit.ps1` | `thinking` | | `PreToolUse` | `pre-tool-use.ps1` | `working` | | `PostToolUse` | `post-tool-use.ps1` | `done`/`error` | | `Stop` | `stop.ps1` | `done` | | `PreCompact` | `pre-compact.ps1` | `thinking` | | `Notification` | `notification.ps1` | `idle` | | `SubagentStart` | `subagent-start.ps1` (CODEX only) | `working` | | `SubagentStop` | `subagent-stop.ps1` (CODEX only) | `done` | | `PermissionRequest`| `permission-request.ps1` (returns `{"decision":"allow"}` so the runtime's fail-closed default does not deny) | `waiting` | | `PermissionDenied`| `permission-denied.ps1` | `error` | 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`). | moment | state | example message | | ----------------------------------------------------- | --------- | ------------------------------ | | receive user task, start reasoning | `thinking`| (none) | | about to invoke any tool | `working` | `"bash: npm test"` | | tool returned 0, before reporting back | `done` | `"3 files modified"` | | tool needs approval (e.g. permission prompt) | `waiting` | `"bash: needs approval"` | | about to call `ask_user` (user must pick) | `waiting` | `"ask_user: 2 options"` | | user answered `ask_user`, resuming work | `done` | `"ask_user answered"` | | tool failed / threw / non-zero exit | `error` | `"compile failed: missing import"` | | conversation idle, waiting for user | `idle` | (none) | **`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: ```powershell # 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: ```powershell $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 ```cmd 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: ```powershell & "<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\`: | file | purpose | | ---------------- | ----------------------------------------------------- | | `status.json` | current state (widget polls this every 400 ms) | | `caller.json` | originating terminal HWND / PID (for click-to-focus) | | `config.json` | pill position, size, opacity (saved on drag) | | `widget.pid` | widget process PID (used by start/stop/status) | | `island.log` | append-only state transition history | | `widget.log` | widget internal debug log | | `show.signal` | transient file written by `mcode-island show` | 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.