ispyx 1.0.0 → 1.0.2

package/README.md

@@ -2,151 +2,107 @@
 
 # ispyx
 
-A local desktop-control [MCP](https://modelcontextprotocol.io) server. It lets an AI assistant use your computer the way a person does: look at the screen or at one window, move the mouse, click, drag, scroll, type, press hotkeys and use the clipboard.
+A local desktop-control [MCP](https://modelcontextprotocol.io) server. It lets an AI assistant use your computer the way a person does: look at the screen, move the mouse, click, drag, scroll, type, press hotkeys and use the clipboard.
 
-- Runs on your machine, talks to the MCP client over **stdio**, opens **no network port**.
-- Node 22+, `koffi` for the Windows API, `@modelcontextprotocol/sdk` for MCP.
-- Windows and macOS (see [Platform status](#platform-status)).
+- Runs on your machine, talks to the AI app over **stdio**, opens **no network port** (the settings panel only listens while it is open).
+- Windows and macOS. Windows needs Node.js 22+; the macOS app carries its own.
+- One resident app (tray icon on Windows, menu-bar icon on macOS) does the work. Every AI app connects through a thin `ispyx mcp` process, so there is one stop key, one banner and one set of settings.
 
-## Features
+## Install
 
-- **Tools** for windows, monitors, screenshots (screen, monitor, region or a single window), mouse (click, move, drag, scroll, press/release), keyboard (typing, hotkeys, hold/release) and clipboard (text, image, files).
-- **Human-paced input.** The pointer glides along a gently curved path to each target, scrolling is smoothed, and typing goes one character at a time with natural pauses.
-- **On-screen feedback.** An eye opens and a scan line sweeps the captured area after a screenshot; clicks, drags, scrolls, key presses, typing and waits each get a small animation; `list_windows` sends out a sonar ping that lights up window frames. A banner shows while a tool runs. All of it is click-through and can be turned off.
-- **Safety.**
-  - **Alt+Esc** (Option+Esc on macOS) stops everything: one press cancels all running and queued calls, a second press within 5 s shuts the server down.
-  - A **denylist** of programs that are never driven (password managers by default).
-  - Refuses to type into **password fields**.
-  - An optional **password gate** that asks you before the first tool call.
-  - An action log of everything the server did.
-  - **Single resident app:** on Windows one background process (`ispyx --resident`, tray icon) does the work and every MCP client talks to it through a thin `ispyx mcp` process, so there is one stop key, one banner and one unlock state.
+### Windows
 
-## Install on Windows
-
-Open PowerShell (Start menu, type "PowerShell") and paste:
+Open PowerShell and paste:
 
 ```
 irm https://raw.githubusercontent.com/murat-mehmet/ispyx/master/scripts/install.ps1 | iex
 ```
 
-No administrator rights are needed. The script explains each step as it goes. It:
-
-- finds Node.js 22+ or installs it for your user only (winget, or the official zip with a checksum check);
-- installs ispyx with `npm install -g ispyx`;
-- puts an `Ispyx` shortcut on your Desktop, turns on start at login and starts ispyx.
+No administrator rights needed. It finds or installs Node.js 22+ for your user, runs `npm install -g ispyx`, adds an `Ispyx` shortcut to your Desktop, turns on start at login and starts ispyx. Manual: install Node.js from [nodejs.org](https://nodejs.org), then `npm i -g ispyx` and run `ispyx`.
 
-Then it prints the commands to connect your AI app, for Claude Code: `claude mcp add ispyx --scope user -- ispyx mcp`.
+Uninstall: run the installer with `-Uninstall` (add `-Purge` to also delete settings and logs). Options and troubleshooting: [docs/windows-install.md](docs/windows-install.md).
 
-**Opening it.** Double-click the `Ispyx` Desktop shortcut or run `ispyx`. ispyx lives in the tray (next to the clock, maybe under the `^` arrow); right-click the icon for its menu (panel, start at login, quit). `ispyx update` updates it. Alt+Esc is the emergency stop.
+### macOS
 
-**Uninstall.** Run the installer again with `-Uninstall` (add `-Purge` to also delete settings and logs):
+Open Terminal and paste:
 
 ```
-& ([scriptblock]::Create((irm https://raw.githubusercontent.com/murat-mehmet/ispyx/master/scripts/install.ps1))) -Uninstall
+curl -fsSL https://github.com/murat-mehmet/ispyx/releases/latest/download/install.sh | sh
 ```
 
-**Manual install.** Install Node.js 22+ from [nodejs.org](https://nodejs.org), then `npm i -g ispyx` and run `ispyx`.
+It downloads the newest `Ispyx.app`, checks it (SHA-256, the developer's signature, notarised) and puts it in `/Applications`, then opens it; allow the two permissions its window asks for. Or download the `.dmg` from the [Releases](https://github.com/murat-mehmet/ispyx/releases) page and drag Ispyx to Applications. The app carries its own Node, nothing else is needed. Uninstall: `... | sh -s -- --uninstall` (add `--purge` for settings and logs). Details: [native/macos/README.md](native/macos/README.md).
 
-Details, options and troubleshooting: [docs/windows-install.md](docs/windows-install.md).
+### Updating
 
-## Install and run (npx, macOS and advanced)
+The panel shows when a newer version is out, with an **Update** button. Or run `ispyx update` (macOS: `/Applications/Ispyx.app/Contents/Resources/ispyx update`, or the install command above again). Windows reinstalls the npm package; macOS replaces the app, which keeps its permissions. Settings and logs stay.
 
-No installation is needed, the client starts it with `npx`.
+## Connect your AI app
 
-Claude Code:
+Open the panel (tray or menu-bar icon, **Open**): it shows the exact command for your machine with a copy button. Or by hand:
 
 ```
-claude mcp add ispyx --scope user -- npx -y ispyx
+claude mcp add ispyx --scope user -- ispyx mcp
 ```
 
-Claude Desktop and other MCP clients (JSON form; on Windows some clients need `cmd /c` around `npx`):
+Other apps (Claude Desktop, LM Studio, ...), JSON form. On Windows some apps need `"command": "cmd", "args": ["/c", "ispyx", "mcp"]`:
 
 ```json
 {
   "mcpServers": {
-    "ispyx": {
-      "command": "npx",
-      "args": ["-y", "ispyx"]
-    }
+    "ispyx": { "command": "ispyx", "args": ["mcp"] }
   }
 }
 ```
 
-Requires Node.js 22 or newer.
-
-### Windows: the resident app
-
-On Windows ispyx is a single resident app, like `Ispyx.app` on macOS:
-
-- `ispyx` (in a console, or from a shortcut) starts the resident app hidden in the background if it is not running, opens its panel and exits.
-- `ispyx --resident` is the resident itself (tray icon, effects, stop key). A second one exits at once. It writes no output; errors go to `%APPDATA%\ispyx\ispyx.log`.
-- `ispyx mcp` is the stdio MCP server for your client. It forwards every call to the resident and starts it first if needed. Prefer registering `npx -y ispyx mcp`; an old registration without `mcp` still works (it is detected by the missing console).
-- `ispyx quit` stops the resident (tray menu: Quit).
+On macOS use `/Applications/Ispyx.app/Contents/Resources/ispyx` as the command, without `mcp`. The AI app starts ispyx when needed, so start at login is optional.
 
-Details: [src/core/RESIDENT.md](src/core/RESIDENT.md).
+## Using it
 
-macOS: install `Ispyx.app` from the [Releases](https://github.com/murat-mehmet/ispyx/releases) page instead, which carries its own Node and needs nothing else. See [native/macos/README.md](native/macos/README.md).
-
-## Configuration
-
-Settings are applied in this order, later wins: built-in defaults, `config.json` (in the package folder, or the file named by `ISPYX_CONFIG`), environment variables. See `config.example.json`.
-
-| `config.json` key | Environment variable | Default | Meaning |
-| --- | --- | --- | --- |
-| (the file itself) | `ISPYX_CONFIG` | `config.json` in the package root | Path of a config file. |
-| `denylist` | `ISPYX_DENYLIST` (comma separated) | `keepass.exe`, `keepassxc.exe`, `1password.exe`, `bitwarden.exe`; macOS: `1Password`, `Bitwarden`, `KeePassXC`, `Keychain Access`, `Enpass` (app names, case-insensitive) | Programs that are never driven or focused. |
-| `logPath` | `ISPYX_LOG` | `logs/actions.jsonl` (macOS: `~/Library/Application Support/Ispyx/logs/actions.jsonl`) | Action log (JSON lines). |
-| `auth` | `ISPYX_AUTH` (`0`/`1`) | `false` | Ask for a password before the first tool call. |
-| `authFile` | `ISPYX_AUTH_FILE` | `%APPDATA%\ispyx\auth.json` (macOS: `~/Library/Application Support/Ispyx/auth.json`) | Where the password hash is stored. |
-| `overlay` | `ISPYX_OVERLAY` (`0`/`1`) | `true` | The "ispyx is working" banner. |
-| `animations` | `ISPYX_ANIMATIONS` (`0`/`1`) | `true` | The eye, scan and other effects. |
-| `typeSpeed` | `ISPYX_TYPE_SPEED` | `1` | Typing speed multiplier (2 = twice as fast, 0 = fixed 8 ms per character). |
-| `stopChord` | `ISPYX_STOP_CHORD` | `alt+esc` | Emergency stop keys (mainly for tests). |
-| `maxTypeLength` | | `10000` | Longest text one `type_text` call accepts. |
-| `moveMinMs`, `moveMaxMs` | | `300`, `1000` | Duration range of pointer glides. |
-| `typeMinMs`, `typeMaxMs`, `typeCapMs` | | `40`, `120`, `60000` | Pause range per typed character; a text is sped up to finish within the cap. |
-
-The older `WIN_INPUT_*` names (and `WIN_INPUT_MCP_CONFIG`) still work as fallbacks; an `ISPYX_*` variable wins when both are set.
+- **Panel.** Permissions (macOS), recent activity, effects, password, denylist, start at login, the connect command. Opens in its own small window and closes when you close it.
+- **Commands.** `ispyx` starts the resident app and opens the panel, `ispyx mcp` is the stdio server for an AI app, `ispyx quit` stops it, `ispyx update` installs the latest version and restarts it. On macOS they are `/Applications/Ispyx.app/Contents/Resources/ispyx update` / `quit` (the app starts the resident itself). Errors go to `%APPDATA%\ispyx\ispyx.log` (macOS: `~/Library/Application Support/Ispyx/ispyx.log`). Details: [src/core/RESIDENT.md](src/core/RESIDENT.md).
+- **Stop.** **Alt+Esc** (Option+Esc on macOS): one press cancels everything running, a second press within 5 s shuts the server down.
+- **Feedback.** A banner shows while a tool runs (green working, amber cancelled, red stopped). An eye and a scan line show on screenshots, clicks, scrolls and typing get small animations. All of it is click-through and can be turned off in the panel.
 
 ## Tools
 
 | Tool | What it does |
 | --- | --- |
-| `list_windows` | Visible top-level windows with handle, title, class, process, rectangle, whether allowed (not denylisted) and whether elevated. |
-| `list_monitors` | Monitor rectangles and the virtual desktop bounds. |
-| `cursor_position` | Current pointer position. |
-| `focus_window` | Restore and bring a window to the front. |
-| `screenshot_screen` | PNG of one monitor, all monitors, or a region. |
-| `screenshot_window` | PNG of one window (also GPU-rendered content), optionally cropped to a region. |
-| `click` | Left, right or middle click; double or triple; with held modifiers. |
-| `move` | Move the pointer. |
-| `mouse_down`, `mouse_up` | Press and release a mouse button. |
-| `drag` | Press at one point, glide to another, release. |
-| `scroll` | Smooth vertical and/or horizontal wheel, with optional modifiers. |
-| `type_text` | Type Unicode text into the focused control at a human pace; refused in password fields. |
-| `press_keys` | Key chords such as `ctrl+v`, `alt+tab`, `win+r`. |
-| `key_down`, `key_up` | Hold and release keys. |
+| `list_windows`, `list_monitors`, `cursor_position` | What is on the desktop and where the pointer is. |
+| `focus_window` | Bring a window to the front. |
+| `screenshot_screen`, `screenshot_window` | PNG of a monitor, all monitors, a region or one window. |
+| `click`, `move`, `drag`, `scroll` | Pointer actions. Clicks take double/triple and held modifiers. |
+| `mouse_down`, `mouse_up` | Press and release a button (the pointer moves straight while one is held). |
+| `type_text`, `press_keys`, `key_down`, `key_up` | Typing, hotkeys such as `ctrl+v`, hold and release. |
+| `get_clipboard`, `set_clipboard` | Read text; write text, an image or a file. |
 | `wait` | Pause up to 60 s. |
-| `get_clipboard`, `set_clipboard` | Read clipboard text; write text, an image or a file. |
 
-Typical flow: `screenshot_screen`, read coordinates off the image, `click` (with `space: "shot"`) or `type_text`, then `screenshot_screen` to check. Details on coordinates and per-tool behaviour are in [docs/behavior.md](docs/behavior.md).
+Typical flow: `screenshot_screen`, read coordinates off the image, `click` (with `space: "shot"`) or `type_text`, then `screenshot_screen` to check. Coordinates and per-tool behaviour: [docs/behavior.md](docs/behavior.md). Input is human-paced: the pointer glides along a curved path, scrolling is smoothed, typing has natural pauses.
 
-## Safety notes
+## Safety
 
-- **Alt+Esc** (Option+Esc on macOS) is the emergency stop. It is caught by a low-level keyboard hook, so it does not also cycle windows.
-- **Elevated (administrator) windows cannot be controlled**: Windows ignores input from a normal process (UIPI). The server refuses with a plain message; it works if the server itself runs elevated. UAC prompts, the lock screen and Ctrl+Alt+Del run on the secure desktop where no input or capture is possible.
-- **Denylist.** Programs on the denylist are never focused, clicked or typed into, and show up as not allowed in `list_windows`. The default covers common password managers.
-- **No credentials.** The server never reads, stores or types saved passwords. Typing into password fields is refused.
-- **Action log.** Every action, refusal and error is logged locally, including typed text (except text aimed at a password field). Clipboard reads log the length only.
-- This tool gives an AI control of your computer. Only connect it to clients you trust, and consider turning on the password gate.
+- **Alt+Esc** is caught by a low-level keyboard hook, so it does not also cycle windows.
+- **Denylist** of programs that are never focused or driven (password managers by default); editable in the panel.
+- **No credentials.** Typing into password fields is refused; ispyx never reads or types saved passwords.
+- **Password gate** (optional, set it in the panel): asks before the first tool call.
+- **Action log.** Every action, refusal and error is logged locally, including typed text (not text aimed at a password field). Clipboard reads log the length only.
+- **Elevated windows** cannot be controlled on Windows (UIPI), and neither can UAC prompts or the lock screen.
+- This gives an AI control of your computer. Connect it only to apps you trust.
 
-## Platform status
+## Configuration
 
-| Platform | Status |
-| --- | --- |
-| Windows | Supported. |
-| macOS | Supported, macOS 13 or later (tested on Apple Silicon with macOS 26; the app is universal, Intel Macs are not tested). A menu-bar app (`native/macos`, `Ispyx.app`) does the OS work and bundles Node and this server. There is no elevation concept; the stop key is Option+Esc. |
-| Linux | Not planned yet. |
+Most settings are in the panel. Files and variables, later wins: built-in defaults, `config.json` (package folder or the file in `ISPYX_CONFIG`), the per-user `%APPDATA%\ispyx\config.json` (macOS: `~/Library/Application Support/Ispyx/`), environment variables. See `config.example.json`.
+
+| Key | Variable | Default |
+| --- | --- | --- |
+| `denylist` | `ISPYX_DENYLIST` (comma separated) | common password managers |
+| `auth` | `ISPYX_AUTH` (`0`/`1`) | `false` |
+| `overlay`, `animations` | `ISPYX_OVERLAY`, `ISPYX_ANIMATIONS` (`0`/`1`) | `true` |
+| `typeSpeed` | `ISPYX_TYPE_SPEED` | `1` (2 = twice as fast) |
+| `stopChord` | `ISPYX_STOP_CHORD` | `alt+esc` |
+| `logPath` | `ISPYX_LOG` | `logs/actions.jsonl` |
+| `authFile` | `ISPYX_AUTH_FILE` | `%APPDATA%\ispyx\auth.json` |
+
+More keys (`maxTypeLength`, `moveMinMs`/`moveMaxMs`, `typeMinMs`/`typeMaxMs`/`typeCapMs`) are in `config.example.json`. The older `WIN_INPUT_*` names still work as fallbacks.
 
 ## Development
 
@@ -154,31 +110,16 @@ Typical flow: `screenshot_screen`, read coordinates off the image, `click` (with
 git clone https://github.com/murat-mehmet/ispyx
 cd ispyx
 npm install
-node src/server.js
+npm test        # unit checks; other scripts in docs/testing.md
 ```
 
-Layout:
-
-- `src/core/` shared, platform independent: MCP server and tools, safety guard, input motion, image encoding, password gate, single-instance IPC.
-- `src/platform/` the platform layer behind `src/platform/index.js`; the contract is in `src/platform/CONTRACT.md`. `win32/` is the Windows implementation (Win32 through `koffi`, PowerShell helpers), `darwin/` the macOS one (a client of `Ispyx.app`).
-- `src/effects/` the on-screen animations.
-- `native/macos/` the macOS app (Swift).
-- `src/server.js` is the entry point (`bin`) and only loads `src/core/server.js`.
-- `test/` tests; most drive the real desktop of the machine they run on.
-
-Releases (npm package and macOS DMG) are made by pushing a version tag, see [docs/releasing.md](docs/releasing.md).
-
-```
-npm test              # unit checks (no desktop needed for most)
-npm run smoke         # drives the real server against Notepad
-npm run motion-test   # pointer glide duration, curvature, exact arrival
-npm run typing-test   # typing pace and accuracy
-npm run instances-test
-npm run shutdown-test
-```
+- `src/core/` shared: MCP server and tools, safety guard, input motion, resident app, panel, password gate.
+- `src/platform/` the OS layer (contract in `src/platform/CONTRACT.md`): `win32/` (Win32 through `koffi`), `darwin/` (a client of `Ispyx.app`).
+- `src/effects/` animations. `native/macos/` the macOS app (Swift). `scripts/install.ps1` the Windows installer.
+- Releases (npm package and macOS DMG) are made by pushing a version tag: [docs/releasing.md](docs/releasing.md).
 
-See [docs/testing.md](docs/testing.md) for all test scripts. Tests use their own `ISPYX_*`/`WIN_INPUT_*` settings (own stop chord, own pipe) so they never interfere with a server you are using.
+Tests drive the real desktop and use their own settings (own stop chord, own pipe), so they never touch a server you are using.
 
 ## License
 
-Not yet decided. `package.json` currently says `UNLICENSED`.
+See [LICENSE](LICENSE).

package/config.example.json

@@ -11,5 +11,6 @@
   "moveMaxMs": 1000,
   "animations": true,
   "overlay": true,
-  "auth": false
+  "auth": false,
+  "updateCheck": true
 }

package/package.json

@@ -1,20 +1,40 @@
 {
   "name": "ispyx",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Local desktop-control MCP server: lets an AI use your keyboard, mouse and screen (windows, screenshots, clicks, typing, clipboard). stdio only, Windows and macOS.",
   "type": "module",
   "main": "src/server.js",
-  "bin": { "ispyx": "src/server.js" },
+  "bin": {
+    "ispyx": "src/server.js"
+  },
   "files": [
     "src/",
     "README.md",
     "LICENSE",
     "config.example.json"
   ],
-  "engines": { "node": ">=22" },
-  "keywords": ["mcp", "model-context-protocol", "computer-use", "desktop-automation", "windows", "macos", "screenshot", "keyboard", "mouse", "claude"],
-  "repository": { "type": "git", "url": "git+https://github.com/murat-mehmet/ispyx.git" },
-  "bugs": { "url": "https://github.com/murat-mehmet/ispyx/issues" },
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "computer-use",
+    "desktop-automation",
+    "windows",
+    "macos",
+    "screenshot",
+    "keyboard",
+    "mouse",
+    "claude"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/murat-mehmet/ispyx.git"
+  },
+  "bugs": {
+    "url": "https://github.com/murat-mehmet/ispyx/issues"
+  },
   "homepage": "https://github.com/murat-mehmet/ispyx#readme",
   "scripts": {
     "start": "node src/server.js",

package/src/core/RESIDENT.md

@@ -12,6 +12,7 @@ process is started with an explicit `--resident` / `mcp` argument (used by tests
 | `ispyx --resident` | The single owner of the pipe (`ipc.listenOwner`). Runs the guard, stop hotkey, effects, tool queue, tray and panel. No stdio. A second resident finds the pipe taken and exits at once (code 0). |
 | `ispyx mcp` | Thin stdio MCP server: same tool list and schemas, every call forwarded with `callOwner`. If no resident runs it starts one first (up to 10 s). If the resident dies mid-call the call returns a tool error. Keeps a watch connection so the resident's shutdown (second stop press, tray Quit) also ends it. |
 | `ispyx quit` | Ask the resident to exit. |
+| `ispyx update` | Stop the resident, `npm install -g ispyx@latest`, start the resident again if it was running (Windows). |
 | `ispyx` without a console on stdin | Old MCP registration pointing at `src/server.js`: behaves as `mcp`. |
 
 Mode selection is `src/core/mode.js`. Start/reach helpers are `src/core/launcher.js`; resident extras are

package/src/core/guard.js

@@ -29,6 +29,7 @@ const DEFAULTS = {
   maxTypeLength: 10000,
   auth: false, // ask for a password (src/auth.js) before the first tool call; env WIN_INPUT_AUTH
   authFile: '', // where the password hash and unlock time live; default %APPDATA%\ispyx\auth.json
+  updateCheck: true, // the resident asks GitHub once a day for a newer release (shown in the panel); env ISPYX_UPDATE_CHECK
 };
 
 /**
@@ -79,6 +80,7 @@ export function loadConfig(source = process.env) {
   if (e('TYPE_SPEED')) cfg.typeSpeed = Number(e('TYPE_SPEED'));
   if (e('OVERLAY')) cfg.overlay = !/^(0|false|no)$/i.test(e('OVERLAY'));
   if (e('ANIMATIONS')) cfg.animations = !/^(0|false|no)$/i.test(e('ANIMATIONS'));
+  if (e('UPDATE_CHECK')) cfg.updateCheck = !/^(0|false|no)$/i.test(e('UPDATE_CHECK'));
   cfg.denylist = cfg.denylist.map((s) => String(s).trim().toLowerCase()).filter(Boolean);
   if (e('LOG')) cfg.logPath = e('LOG');
   cfg.logPath = path.resolve(ROOT, cfg.logPath);

package/src/core/launcher.js

@@ -1,5 +1,8 @@
 // Starting and reaching the resident app (resident model). No platform import: usable before anything is loaded.
-import { spawn } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { callOwner, OwnerGone, pipeName } from './ipc.js';
 
@@ -13,12 +16,30 @@ function macApp() {
   return m ? m[1] : null;
 }
 
+const MAC_BUNDLE_ID = 'com.ispyx.app';
+/** Where Ispyx.app's resident listens (macos-entry.js pins it there for the app's own processes). */
+export const macAppPipe = () => path.join(os.homedir(), 'Library', 'Application Support', 'Ispyx', 'ispyx.sock');
+
+/**
+ * ispyx from npm/npx on a Mac with Ispyx.app installed: forward to the app's resident instead of running a second
+ * server of its own (one stop key, one banner, the calls in the panel). Not for tests (ISPYX_PLATFORM) or an explicit
+ * ISPYX_PIPE. Returns true when this process should be the `mcp` forwarder.
+ */
+export function useMacAppResident(env = process.env) {
+  if (process.platform !== 'darwin' || macApp() || env.ISPYX_PLATFORM || env.ISPYX_PIPE) return false;
+  const installed = ['/Applications', path.join(os.homedir(), 'Applications')].some((d) => fs.existsSync(path.join(d, 'Ispyx.app')));
+  if (!installed) return false;
+  env.ISPYX_PIPE = macAppPipe();
+  return true;
+}
+
 /** Starts `ispyx --resident` detached and hidden, with this process's environment (same pipe). Inside Ispyx.app it
  * opens the app instead, which starts the resident itself. */
 export function spawnResident() {
   const app = macApp();
-  const child = app
-    ? spawn('open', ['-g', app, '--args', '--background'], { stdio: 'ignore', detached: true })
+  const forApp = app || (process.platform === 'darwin' && process.env.ISPYX_PIPE === macAppPipe());
+  const child = forApp
+    ? spawn('open', ['-g', ...(app ? [app] : ['-b', MAC_BUNDLE_ID]), '--args', '--background'], { stdio: 'ignore', detached: true })
     : spawn(process.execPath, [ENTRY, '--resident'], { detached: true, windowsHide: true, stdio: 'ignore' });
   child.on('error', () => {});
   child.unref();
@@ -63,8 +84,45 @@ export async function runLauncher() {
   process.exit(0);
 }
 
+/**
+ * `ispyx update`. Windows: stops the resident (it holds files open), installs the latest package, starts it again if
+ * it ran. macOS: the app is updated as a whole (it is signed), by scripts/install.sh from the latest release.
+ */
+export async function runUpdate() {
+  if (process.platform === 'darwin') {
+    const { MAC_INSTALL_URL } = await import('./updates.js');
+    const code = await new Promise((resolve) => {
+      const c = spawn('/bin/sh', ['-c', `curl -fsSL ${MAC_INSTALL_URL} | sh`], { stdio: 'inherit' });
+      c.on('error', () => resolve(1));
+      c.on('exit', (n) => resolve(n ?? 1));
+    });
+    process.exit(code);
+  }
+  const pipe = pipeName();
+  const wasRunning = await residentRunning(pipe);
+  if (wasRunning) {
+    try { await callOwner(pipe, '__quit', {}); } catch { /* gone before answering */ }
+    for (let i = 0; i < 40 && await residentRunning(pipe); i++) await sleep(150);
+  }
+  const code = await new Promise((resolve) => {
+    const c = spawn('npm', ['install', '-g', 'ispyx@latest'], { stdio: 'inherit', shell: true });
+    c.on('error', () => resolve(1));
+    c.on('exit', (n) => resolve(n ?? 1));
+  });
+  if (code !== 0) process.stderr.write('ispyx: the update failed (see the npm output above).\n');
+  // Start the new copy: npm replaced the files in place, so a fresh process loads them.
+  if (wasRunning) spawnResident();
+  process.exit(code);
+}
+
 /** `ispyx quit`: asks the resident to exit; exits 0 either way. */
 export async function runQuit() {
+  // macOS: the app would start its resident again; quitting the app ends it and the forwarders
+  useMacAppResident();
+  if (process.platform === 'darwin' && (macApp() || process.env.ISPYX_PIPE === macAppPipe())) {
+    spawnSync('osascript', ['-e', `quit app id "${MAC_BUNDLE_ID}"`], { stdio: 'ignore', timeout: 10000 });
+    process.exit(0);
+  }
   try { await callOwner(pipeName(), '__quit', {}); } catch { /* not running, or gone before answering */ }
   process.exit(0);
 }

package/src/core/mode.js

@@ -11,6 +11,7 @@ export function resolveMode(argv = process.argv.slice(2), env = process.env, pla
   if (argv.includes('--resident')) return 'resident';
   if (argv.includes('mcp')) return 'mcp';
   if (argv.includes('quit') || argv.includes('--quit')) return 'quit';
+  if (argv.includes('update')) return 'update';
   const target = env.ISPYX_PLATFORM || platform;
   if (target === 'win32') return isTTY ? 'launcher' : 'mcp';
   return 'classic';

package/src/core/panel/index.js

@@ -8,7 +8,7 @@ import { fileURLToPath } from 'node:url';
 const PAGE = fileURLToPath(new URL('./page.html', import.meta.url));
 const COOKIE = 'ispyx_panel';
 // Explicit whitelist; an action is also callable only if the host's `actions` object defines it.
-const ACTIONS = ['quit', 'setAutostart', 'setEffects', 'openLog', 'copy', 'close', 'requestPermission', 'openPermissionSettings', 'showConfigFile', 'clearRecent', 'addDeny', 'removeDeny', 'setPassword', 'setAuthRequired'];
+const ACTIONS = ['quit', 'setAutostart', 'setEffects', 'openLog', 'copy', 'close', 'requestPermission', 'openPermissionSettings', 'showConfigFile', 'clearRecent', 'addDeny', 'removeDeny', 'setPassword', 'setAuthRequired', 'update', 'checkUpdate'];
 const BOOL_ACTIONS = new Set(['setAutostart', 'setEffects']);
 const STRING_ACTIONS = new Set(['copy', 'requestPermission', 'openPermissionSettings', 'addDeny']); // value must be a short string
 // value is an object of short strings (and a boolean for setAuthRequired.on)

package/src/core/panel/page.html

@@ -17,6 +17,8 @@ header{display:flex;align-items:center;gap:14px;margin-bottom:18px}
 header img{width:44px;height:44px;flex:none;border-radius:10px}
 h1{font-size:17px;line-height:1.25;margin:0;font-weight:700}
 .sub{color:var(--mute);font-size:12px;margin-top:2px;overflow-wrap:anywhere}
+.upd{display:flex;align-items:center;gap:8px;margin-top:6px;color:var(--fg)}
+.upd button{padding:2px 10px;font-size:12px}
 .dot{display:inline-block;width:8px;height:8px;border-radius:50%;background:var(--mute);margin-right:6px;vertical-align:1px}
 .run .dot{background:var(--acc);box-shadow:0 0 0 3px rgba(47,209,107,.22)}
 .warn .dot{background:var(--warn)}
@@ -93,6 +95,7 @@ button.link:hover{background:none;color:var(--fg)}
     <h1 id="head">Ispyx</h1>
     <div class="sub" id="state"><span class="dot"></span><span id="stateTxt">Connecting</span></div>
     <div class="sub" id="meta"></div>
+    <div class="sub upd" id="upd" hidden><span id="updTxt"></span> <button type="button" class="pri" id="updBtn">Update</button></div>
   </div>
 </header>
 <div id="off" hidden>Ispyx has quit. You can close this window.</div>
@@ -269,6 +272,9 @@ function render(s){
   if(typeof s.uptimeMs==="number")meta.push("up "+fmt(s.uptimeMs));
   if(s.pid!=null)meta.push("pid "+s.pid);
   setText("meta",meta.join(" · "));
+  var u=s.update;
+  show("upd",!!(u&&u.available));
+  if(u&&u.available&&!updating)setText("updTxt","Version "+u.latest+" is available.");
 
   show("sPerm",!!(perms&&perms.length));
   if(perms&&perms.length)renderPerms(perms);
@@ -421,6 +427,12 @@ $("cfgShow").addEventListener("click",function(){act("showConfigFile")});
 $("log").addEventListener("click",function(){act("openLog")});
 $("showAll").addEventListener("click",function(){expanded=!expanded;if(last&&last.recent)renderRecent(last.recent,last.recentTotal)});
 $("clearAct").addEventListener("click",function(){act("clearRecent").then(poll)});
+// the update quits and restarts ispyx: this window then reports it has quit (macOS opens it again)
+var updating=false;
+$("updBtn").addEventListener("click",function(){
+  updating=true;$("updBtn").disabled=true;setText("updTxt","Updating, ispyx restarts in a moment…");
+  act("update").catch(function(err){updating=false;$("updBtn").disabled=false;setText("updTxt",err.message)});
+});
 $("end").addEventListener("click",function(){
   if(last&&last.platform==="darwin"){act("close");return}
   if(!confirm("Quit Ispyx? AI tools lose access until it is reopened."))return;

package/src/core/resident.js

@@ -22,6 +22,7 @@ import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 
 import { saveUserConfig } from './guard.js';
+import { startUpdateCheck, launchUpdate } from './updates.js';
 import { PasswordError } from './auth.js';
 
 /** A refusal whose message goes to the person at the panel. */
@@ -119,6 +120,8 @@ const safe = (fn, dflt) => { try { return fn(); } catch { return dflt; } };
 export function panelModel(ctx) {
   const { w, config, guard, auth, scan, clients } = ctx;
   const t0 = Date.now();
+  // never from tests (fake platform): they must not depend on the network
+  const updates = startUpdateCheck({ current: VERSION, enabled: config.updateCheck !== false && w.name !== 'fake' });
   const save = (patch) => {
     try { saveUserConfig(patch); } catch (e) { throw new PanelError(`Could not save the setting: ${e.message}`); }
   };
@@ -135,6 +138,7 @@ export function panelModel(ctx) {
     passwordSet: safe(() => auth.passwordSet(), false),
     authRequired: !!config.auth,
     denylist: config.denylist.slice(),
+    ...(updates.state() ? { update: updates.state() } : {}),
   });
   const actions = {
     setEffects: (on) => { scan.enabled = !!on; config.animations = !!on; save({ animations: !!on }); return !!on; },
@@ -163,8 +167,15 @@ export function panelModel(ctx) {
       save({ denylist: config.denylist.slice() });
     },
     clearRecent: () => { recent.length = 0; },
+    // the newer release: installs it in a process of its own, which quits and restarts ispyx (this one included)
+    update: () => {
+      if (!updates.state()?.available) throw new PanelError('This is the newest version.');
+      launchUpdate({ platform: w.name, dataDir: w.dataDir() });
+      return true;
+    },
+    checkUpdate: async () => { await updates.check(); return updates.state(); },
   };
-  return { getState, actions };
+  return { getState, actions, stop: () => updates.stop() };
 }
 
 /**

package/src/core/server.js

@@ -13,13 +13,14 @@ import { Auth } from './auth.js';
 import { ScanAnimation, keyLabels } from '../effects/scan.js';
 import { pipeName, listenOwner, callOwner, watchOwner, OwnerGone } from './ipc.js';
 import { resolveMode } from './mode.js';
-import { ensureResident } from './launcher.js';
+import { ensureResident, useMacAppResident } from './launcher.js';
 import { panelModel, recordCall, setupLogging, startResident } from './resident.js';
 
 const { parseSequence, insertsContent, Overlay, installStopHotkey } = w;
 
 // Windows: one resident app does the work and `ispyx mcp` forwards to it (see RESIDENT.md). Elsewhere: classic election.
-const mode = resolveMode();
+// npm/npx on a Mac with Ispyx.app installed: forward to the app's resident rather than run a second server
+const mode = resolveMode() === 'classic' && useMacAppResident() ? 'mcp' : resolveMode();
 const config = loadConfig();
 // Only the process that owns the pipe (see ipc.js) does the work; the others forward their tool calls to it.
 let guard, overlay, auth, stopHook = null;

package/src/core/updates.js

@@ -0,0 +1,83 @@
+// Newer-release check for the panel and `ispyx update`. Asks GitHub which release is the latest (an outgoing HTTPS
+// request, no API key, no data sent), at most once a day; config `updateCheck: false` turns it off.
+// Updating stays per platform:
+//   Windows  `ispyx update`: stop the resident, npm install -g ispyx@latest, start it again (launcher.js)
+//   macOS    scripts/install.sh from the latest release: checks and swaps Ispyx.app, then opens it again
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const REPO = 'murat-mehmet/ispyx';
+export const MAC_INSTALL_URL = `https://github.com/${REPO}/releases/latest/download/install.sh`;
+const ENTRY = fileURLToPath(new URL('../server.js', import.meta.url));
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/** 1 when a is newer than b, -1 when older, 0 when equal; "1.2.10" > "1.2.9", a release beats its pre-release. */
+export function compareVersions(a, b) {
+  const parse = (v) => {
+    const [main, pre = ''] = String(v).replace(/^v/, '').split('-', 2);
+    return { nums: main.split('.').map((n) => Number(n) || 0), pre };
+  };
+  const x = parse(a), y = parse(b);
+  for (let i = 0; i < Math.max(x.nums.length, y.nums.length); i++) {
+    const d = (x.nums[i] ?? 0) - (y.nums[i] ?? 0);
+    if (d) return Math.sign(d);
+  }
+  if (x.pre === y.pre) return 0;
+  if (!x.pre) return 1;
+  if (!y.pre) return -1;
+  return x.pre > y.pre ? 1 : -1;
+}
+
+/** The version of the latest release, from the redirect of /releases/latest (no API call, so no rate limit). */
+export async function latestVersion({ fetchImpl = fetch, timeoutMs = 10000 } = {}) {
+  const res = await fetchImpl(`https://github.com/${REPO}/releases/latest`, {
+    method: 'HEAD', redirect: 'manual', signal: AbortSignal.timeout(timeoutMs),
+  });
+  const m = /\/releases\/tag\/v?([^/?#]+)$/.exec(res.headers.get('location') ?? '');
+  if (!m) throw new Error(`no latest release found (HTTP ${res.status})`);
+  return decodeURIComponent(m[1]);
+}
+
+/**
+ * Checks shortly after start and then once a day. state() is { current, latest, available } once a check has
+ * answered, else null; a failed check (offline) keeps the last answer and is retried on the next round.
+ */
+export function startUpdateCheck({ current, enabled = true, firstDelayMs = 15000, fetchImpl } = {}) {
+  let latest = null;
+  const check = async () => {
+    try { latest = await latestVersion({ fetchImpl }); } catch { /* offline or GitHub down: try again later */ }
+  };
+  const timers = [];
+  if (enabled) {
+    const t = setTimeout(check, firstDelayMs);
+    const i = setInterval(check, DAY_MS);
+    t.unref?.();
+    i.unref?.();
+    timers.push(t, i);
+  }
+  return {
+    check,
+    state: () => (latest ? { current, latest, available: compareVersions(latest, current) > 0 } : null),
+    stop: () => { for (const t of timers) clearTimeout(t); },
+  };
+}
+
+/**
+ * Starts the update in a process of its own (the update quits the running ispyx, this process included) and
+ * returns at once. Its output goes to update.log in the data directory.
+ */
+export function launchUpdate({ platform = process.platform, dataDir }) {
+  let out = 'ignore';
+  try {
+    fs.mkdirSync(dataDir, { recursive: true });
+    out = fs.openSync(path.join(dataDir, 'update.log'), 'w');
+  } catch { /* no log then */ }
+  const child = platform === 'darwin'
+    ? spawn('/bin/sh', ['-c', `curl -fsSL ${MAC_INSTALL_URL} | sh`], { detached: true, stdio: ['ignore', out, out] })
+    : spawn(process.execPath, [ENTRY, 'update'], { detached: true, windowsHide: true, stdio: ['ignore', out, out] });
+  child.on('error', () => {});
+  child.unref();
+  if (typeof out === 'number') fs.closeSync(out);
+}

package/src/macos-entry.js

@@ -1,16 +1,16 @@
 // Entry point used by Ispyx.app: the app starts it as the resident (`--resident`), and the MCP launcher
-// (Contents/Resources/ispyx) as the thin forwarder (`mcp`). Picks the platform automatically (darwin), whatever the
-// environment of the MCP client says, then runs the normal server.
+// (Contents/Resources/ispyx) as the thin forwarder (`mcp`), or for `update` / `quit`. Picks the platform
+// automatically (darwin), whatever the environment of the MCP client says, then runs the normal entry point.
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
+import { macAppPipe } from './core/launcher.js';
 
 delete process.env.ISPYX_PLATFORM;
 // The app's resident and every forwarder meet on one socket in the app's data folder, whatever their environment
-// (an MCP client may give its children another temp directory).
+// (an MCP client may give its children another temp directory). npm copies on this Mac use it too (launcher.js).
 if (!process.env.ISPYX_PIPE) {
-  const dir = path.join(os.homedir(), 'Library', 'Application Support', 'Ispyx');
-  try { fs.mkdirSync(dir, { recursive: true, mode: 0o700 }); } catch { /* reported when listening fails */ }
-  process.env.ISPYX_PIPE = path.join(dir, 'ispyx.sock');
+  const sock = macAppPipe();
+  try { fs.mkdirSync(path.dirname(sock), { recursive: true, mode: 0o700 }); } catch { /* reported when listening fails */ }
+  process.env.ISPYX_PIPE = sock;
 }
-await import('./core/server.js');
+await import('./server.js'); // the entry point: picks resident / mcp / update / quit

package/src/server.js

@@ -4,6 +4,7 @@
 //   ispyx --resident the resident app (tray, panel, tool queue)
 //   ispyx mcp        stdio MCP server forwarding to the resident (started on demand)
 //   ispyx quit       ask the resident to exit
+//   ispyx update     stop the resident, npm install -g ispyx@latest, start it again
 // Windows without a console on stdin (an old MCP registration) behaves as `mcp`. Other platforms run the
 // classic server (core/server.js), unchanged. See src/core/RESIDENT.md.
 import { resolveMode } from "./core/mode.js";
@@ -11,4 +12,5 @@ import { resolveMode } from "./core/mode.js";
 const mode = resolveMode();
 if (mode === "launcher") await (await import("./core/launcher.js")).runLauncher();
 else if (mode === "quit") await (await import("./core/launcher.js")).runQuit();
+else if (mode === "update") await (await import("./core/launcher.js")).runUpdate();
 else await import("./core/server.js");