local-commander-agent 0.3.44 → 0.3.46

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Change history
 
+## 0.3.46 - 2026-10-22
+
+- Simpler setup on macOS and Linux: the approval page opens in your browser by itself, and on a Mac access is one click in a window (Full Access, or Choose Folder). Linux asks one question in the terminal: press Enter for Full Access or type a folder.
+- Fixed: on macOS, updates keep access to the agent's key in the Keychain.
+- Includes everything in 0.3.45.
+
+## 0.3.45 - 2026-10-22
+
+- New: macOS 14 or later on Apple Silicon, and Linux x64 or arm64 with a systemd user session. Run the same `npx local-commander-agent@latest` in Terminal; npm downloads only the runtime for your computer. Setup pairs the computer, asks what may be used in the terminal, and runs the agent as a background service that starts when you sign in.
+- Fixed: a computer that lost its connection without noticing (after sleep, a network change or a server restart) now reconnects within about three minutes instead of staying offline.
+- Fixed: a request that never reached a sleeping computer no longer keeps one of its execution slots busy; the computer frees it when it reconnects.
+- Includes everything in 0.3.44.
+
 ## 0.3.44 - 2026-10-22
 
 - New: when you set up a computer, the window that asks what may be used now shows the Local Commander account the computer joined. Someone helping you can approve your computer from their own phone with the code you read to them. Continue only if you know that account; Cancel shares nothing.

package/README.md

@@ -1,25 +1,25 @@
 # Local Commander Agent
 
-**Connect your AI assistant to your Windows computer through [Local Commander](https://localcmd.app).** The agent lets an authorized MCP client work with local files, run explicitly approved commands, and access approved localhost services on your paired computer.
+**Connect your AI assistant to your computer through [Local Commander](https://localcmd.app).** The agent lets an authorized MCP client work with local files, run explicitly approved commands, and access approved localhost services on your paired computer.
 
-> **Requires the Local Commander service at https://localcmd.app.** This npm package is its Windows companion, not a standalone MCP server, an offline AI assistant, or a JavaScript SDK. Installing the package alone is not enough: you need a Local Commander account, an approved device pairing, a running agent, an internet connection, and an authorized MCP connection from your AI client. Local management commands such as status and stop do not require the service to be online.
+> **Requires the Local Commander service at https://localcmd.app.** This npm package is its computer companion, not a standalone MCP server, an offline AI assistant, or a JavaScript SDK. Installing the package alone is not enough: you need a Local Commander account, an approved device pairing, a running agent, an internet connection, and an authorized MCP connection from your AI client. Local management commands such as status and stop do not require the service to be online.
 
 [Website and sign-in](https://localcmd.app) ┬╖ [Support](https://localcmd.app/support) ┬╖ [Privacy](https://localcmd.app/privacy)
 
 ## Before you start
 
-Use **Windows 11 x64** and a currently supported Node.js LTS version meeting the package's Node.js 20+ minimum. Node.js/npm are needed to launch `npx`; the installed background agent includes its own Node runtime. You do not need Docker, WSL, a repository checkout, a database, or administrator rights for normal setup. Your AI client must support authenticated remote MCP connections; availability depends on the client and workspace policy.
+Use **Windows 11 x64**, **macOS 14 or later on Apple Silicon**, or **Linux with a systemd user session** (Ubuntu 24.04 x64 or arm64), and a currently supported Node.js LTS version meeting the package's Node.js 20+ minimum. Node.js/npm are needed to launch `npx`; the installed background agent includes its own Node runtime. You do not need Docker, WSL, a repository checkout, a database, or administrator rights for normal setup. Your AI client must support authenticated remote MCP connections; availability depends on the client and workspace policy.
 
 ## Install and connect
 
-1. Open PowerShell or Windows Terminal as your normal Windows user and run:
+1. Open a terminal as your normal user (PowerShell or Windows Terminal on Windows, Terminal on macOS or Linux) and run:
 
    ```powershell
    npx local-commander-agent@latest
    ```
 
 2. The installer opens a browser. Sign in to [Local Commander](https://localcmd.app), check the displayed pairing code, and approve this computer. Approve only a pairing you just started yourself.
-3. Choose access in the local Windows dialog:
+3. Choose access in the local window (on Windows and macOS; Linux asks one question in the terminal):
    - **Full access - all connected drives (default):** approve the available drive letters, file reads/writes, installed commands and localhost services at once. There is no folder picker or separate approval for Node.
    - **Selected folders:** choose one folder in the folder picker. It starts read/write; more folders and write permission can be added later.
 
@@ -32,15 +32,15 @@ Use **Windows 11 x64** and a currently supported Node.js LTS version meeting the
 
    Complete the browser authorization with the same Local Commander account. Device pairing and AI-client authorization are separate steps. For an AI client that runs on this same computer, you can instead use direct local MCP (see "Direct local MCP" below). Do not configure `npx local-commander-agent` itself as a stdio server.
 
-You can close the installation terminal. The agent runs in the background and starts when this Windows user signs in. The PC must be awake and online for remote AI tasks. As a first test, ask the connected assistant to list the files in a folder you approved.
+You can close the installation terminal. The agent runs in the background and starts when you sign in to this computer. The computer must be awake and online for remote AI tasks. As a first test, ask the connected assistant to list the files in a folder you approved.
 
-Installation and update also add `localcommander` to your Windows **user PATH**. Open a new CMD/terminal window, then run `localcommander status`, `localcommander monitor --watch`, or `localcommander logs --follow` from any folder. No global npm installation is needed. The launcher uses your required Node.js installation and an installed copy of the CLI, so clearing npm's cache does not remove the command. Fetch newer releases with `npx local-commander-agent@latest update`. Uninstall removes Local Commander's PATH entry and launcher while preserving your other entries.
+On Windows, installation and update also add `localcommander` to your **user PATH**. Open a new CMD/terminal window, then run `localcommander status`, `localcommander monitor --watch`, or `localcommander logs --follow` from any folder. No global npm installation is needed. The launcher uses your required Node.js installation and an installed copy of the CLI, so clearing npm's cache does not remove the command. Fetch newer releases with `npx local-commander-agent@latest update`. Uninstall removes Local Commander's PATH entry and launcher while preserving your other entries.
 
 ## Direct local MCP (AI clients on this computer)
 
-An AI client that runs on the same Windows computer, such as Claude Code, Codex or Cursor, can use your approved workspaces directly through the running agent. No cloud round trip happens per call. It keeps working while the internet or localcmd.app is unavailable, and calls take milliseconds instead of a cloud admission. Hosted assistants such as ChatGPT or claude.ai on the web still use `https://localcmd.app/mcp`.
+An AI client that runs on the same computer, such as Claude Code, Codex or Cursor, can use your approved workspaces directly through the running agent. No cloud round trip happens per call. It keeps working while the internet or localcmd.app is unavailable, and calls take milliseconds instead of a cloud admission. Hosted assistants such as ChatGPT or claude.ai on the web still use `https://localcmd.app/mcp`.
 
-1. Turn it on once. This is an owner choice for this Windows user, and `off` revokes it immediately:
+1. Turn it on once. This is an owner choice for this user account, and `off` revokes it immediately:
 
    ```powershell
    localcommander mcp on
@@ -57,15 +57,15 @@ An AI client that runs on the same Windows computer, such as Claude Code, Codex
    Other clients:  { "command": "cmd", "args": ["/c", "localcommander", "mcp"] }
    ```
 
-The tools are the same as the remote ones: `workspace_list`, file reads and writes, search, Git, `project_snapshot`, `command_run` and `localhost_request`. Each takes an optional `workspace` (a grant id, a root such as `D:\`, or a display name). The same workspace grants, Full Access or scoped mode and owner denials apply, and commands run hidden with your Windows account's rights.
+The tools are the same as the remote ones: `workspace_list`, file reads and writes, search, Git, `project_snapshot`, `command_run` and `localhost_request`. Each takes an optional `workspace` (a grant id, a root such as `D:\`, or a display name). The same workspace grants, Full Access or scoped mode and owner denials apply, and commands run hidden with your user account's rights.
 
-The agent listens only on `127.0.0.1`, and only while direct local MCP is on. Every connection must first prove a key that only this Windows user's protected Local Commander state can derive, so other Windows users and other computers cannot connect. Check the state with `localcommander mcp status`; turn it off with `localcommander mcp off`. While an enterprise Guard policy is configured, direct local calls are refused so that Guard evidence cannot be bypassed.
+The agent listens only on `127.0.0.1`, and only while direct local MCP is on. Every connection must first prove a key that only this user's protected Local Commander state can derive, so other users and other computers cannot connect. Check the state with `localcommander mcp status`; turn it off with `localcommander mcp off`. While an enterprise Guard policy is configured, direct local calls are refused so that Guard evidence cannot be bypassed.
 
 ## What тАЬall connected drivesтАЭ means
 
 It expands the **filesystem scope** to the drive letters shown at the moment you consent. It includes available local fixed and removable drives. Mapped network drives and `subst` letters are not included. New drive letters, unavailable drives and unmounted volumes are not automatically added; run `configure-access` again after making the desired drive available. Grants are path/drive-letter based, not tied to a particular removable disk's hardware identity: reusing an approved letter gives access under that letter.
 
-Full access allows installed commands resolved from absolute owner PATH entries or an absolute executable path, plus localhost services. Explicit command/port denials and write restrictions still apply. It does not elevate Windows privileges. Protected Local Commander state/runtime and secret-file filters apply to file tools; programs run with your Windows account's rights, so these controls are not an OS sandbox. ChatGPT/Claude or your workspace may still ask for their own action confirmations. Existing installations keep their current permissions until the owner runs `configure-access` and selects full access using a release that supports it.
+Full access allows installed commands resolved from absolute owner PATH entries or an absolute executable path, plus localhost services. Explicit command/port denials and write restrictions still apply. It does not elevate privileges. Protected Local Commander state/runtime and secret-file filters apply to file tools; programs run with your user account's rights, so these controls are not an OS sandbox. ChatGPT/Claude or your workspace may still ask for their own action confirmations. Existing installations keep their current permissions until the owner runs `configure-access` and selects full access using a release that supports it.
 
 ## Manage the installation
 
@@ -143,7 +143,7 @@ Do not paste `(Get-Command git).Source` into CMD: CMD passes it literally instea
 
 Under full access, `deny-command` and `deny-localhost` exclude the named command or port while other commands/ports remain available. Native `.exe`/`.com` commands receive argument arrays directly. `.cmd`/`.bat` launchers use a hidden PowerShell wrapper and reject cmd metacharacters in arguments; use an explicit interpreter for more complex scripts. Allowing a general interpreter is not containment against it launching a denied program.
 
-Under **owner-approved Full Access**, installed Windows shells, script hosts and administration executables (including PowerShell and CMD) work without per-command registration. They execute under the Windows account's own rights, not elevated privileges. Owner-defined `deny-command` exclusions and explicit write/localhost restrictions still apply. A general interpreter can access resources beyond file-tool path checks; Full Access is not an OS sandbox. Existing scoped grants stay scoped until the owner deliberately changes access with `configure-access`.
+Under **owner-approved Full Access**, installed Windows shells, script hosts and administration executables (including PowerShell and CMD) work without per-command registration. They execute under the user account's own rights, not elevated privileges. Owner-defined `deny-command` exclusions and explicit write/localhost restrictions still apply. A general interpreter can access resources beyond file-tool path checks; Full Access is not an OS sandbox. Existing scoped grants stay scoped until the owner deliberately changes access with `configure-access`.
 
 
 For a remote MCP client with an unknown device/workspace, use `workspace_list`, then `execution_session_open`, perform the requested work and read results. Reuse valid, already authorized session and target context where supported. `diagnostics` is for faults, not a mandatory startup roundtrip. Diagnostics reports quota separately from the device's execution slot limit. Its optional `repairSafe` mode releases only expired reservations from this OAuth connection that never acquired a dispatch lease. It never retries work, changes permissions or clears unknown executions.
@@ -153,7 +153,7 @@ For a remote MCP client with an unknown device/workspace, use `workspace_list`,
 | Symptom | What to check |
 | --- | --- |
 | `npx` is not recognized | Install supported Node.js LTS, then open a new terminal. |
-| Unsupported OS or architecture | This package targets Windows x64, not macOS, Linux or Windows ARM64. |
+| Unsupported OS or architecture | Supported: Windows 11 x64, macOS 14 or later on Apple Silicon, Linux x64 or arm64 with systemd. Windows ARM64 and Intel Macs are not supported. |
 | Pairing does not complete | Open https://localcmd.app, verify your account and internet access, then rerun the install command to resume. Do not share pairing codes. |
 | `ACCESS_SETUP_CANCELLED` | No filesystem grant was saved by that dialog. Rerun setup and choose the intended scope. |
 | `STATE_CHANGED` | Local account/policy/permissions changed while the dialog was open. Review current state and reopen the dialog. |

package/bin/localcommander.mjs

@@ -723,8 +723,10 @@ function help() {
   ].join("\n");
 }
 async function main() {
-  requireWindows();
   if (!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/u.test(VERSION)) fail("PACKAGE_VERSION_INVALID");
+  // macOS and Linux run the per-platform runtime package through its own lifecycle (#253).
+  if (process.platform !== "win32") return (await import("./posix.mjs")).runPosix(process.argv.slice(2), VERSION);
+  requireWindows();
   const command = process.argv[2] || "bootstrap";
   const args = process.argv.slice(3);
   if (command === "-h" || command === "--help" || command === "help") {

package/bin/posix.mjs

@@ -0,0 +1,66 @@
+// macOS and Linux: the runtime ships in a per-platform package (an optional dependency, so npm installs only the
+// matching one). Its lifecycle accepts only a private, owner-only artifact directory, so the files are copied from the
+// npx cache into a fresh private directory and the lifecycle installs from there into its own versions directory.
+import { constants } from "node:fs";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+
+const PACKAGES = { "darwin-arm64": "local-commander-agent-darwin-arm64", "linux-x64": "local-commander-agent-linux-x64", "linux-arm64": "local-commander-agent-linux-arm64" };
+// npm command -> lifecycle command. The default (`npx local-commander-agent@latest`) is setup, as on Windows.
+const COMMANDS = { bootstrap: "setup", install: "setup", setup: "setup", update: "update", pair: "pair", access: "access", "configure-access": "access",
+  start: "start", stop: "stop", status: "status", rollback: "rollback", uninstall: "uninstall" };
+const EXECUTABLES = new Set(["node", "posix-host", "owner-store"]);
+
+function fail(code) { const error = new Error(code); error.code = code; throw error; }
+
+export function posixHelp() {
+  return [
+    "Local Commander",
+    "",
+    "  npx local-commander-agent@latest            set up this computer, pair it and choose access",
+    "  npx local-commander-agent@latest update     install this version, keeping pairing and access",
+    "  npx local-commander-agent@latest status|start|stop|pair|access|rollback",
+    "  npx local-commander-agent@latest uninstall [--purge-state]",
+    ""
+  ].join("\n");
+}
+
+export async function runPosix(argv, version) {
+  const name = PACKAGES[process.platform + "-" + process.arch];
+  if (!name) fail(process.platform === "darwin" ? "MACOS_APPLE_SILICON_REQUIRED" : process.platform === "linux" ? "LINUX_X64_OR_ARM64_REQUIRED" : "PLATFORM_UNSUPPORTED");
+  const command = argv[0] || "bootstrap", args = argv.slice(1);
+  if (command === "-h" || command === "--help" || command === "help") { process.stdout.write(posixHelp()); return; }
+  const lifecycle = COMMANDS[command];
+  if (!lifecycle) fail("ARGUMENT_INVALID");
+  if (lifecycle === "uninstall" ? args.length > 1 || (args.length === 1 && args[0] !== "--purge-state") : args.length) fail("ARGUMENT_INVALID");
+  if (typeof process.getuid === "function" && process.getuid() === 0) fail("POSIX_OWNER_REQUIRED");
+
+  let packageJson;
+  try { packageJson = createRequire(import.meta.url).resolve(name + "/package.json"); } catch { fail("PLATFORM_PACKAGE_MISSING"); }
+  const meta = JSON.parse(await fs.readFile(packageJson, "utf8"));
+  if (meta.name !== name || meta.version !== version) fail("PLATFORM_PACKAGE_MISMATCH");
+  const source = path.join(path.dirname(packageJson), "runtime");
+  const manifest = JSON.parse(await fs.readFile(path.join(source, "manifest.json"), "utf8"));
+  const files = Object.keys(manifest?.files ?? {});
+  if (manifest?.platform !== process.platform || manifest?.arch !== process.arch || !files.length || files.some(file => !/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/u.test(file))) fail("PLATFORM_PACKAGE_INVALID");
+
+  // Canonical parent: on macOS os.tmpdir() is under /var, a symlink to /private/var, and the lifecycle rejects aliases.
+  const stage = await fs.mkdtemp(path.join(await fs.realpath(os.tmpdir()), "local-commander-"));
+  try {
+    await fs.chmod(stage, 0o700);
+    for (const file of [...files, "manifest.json"]) {
+      const target = path.join(stage, file);
+      await fs.copyFile(path.join(source, file), target, constants.COPYFILE_EXCL);
+      await fs.chmod(target, EXECUTABLES.has(file) ? 0o700 : 0o600);
+    }
+    // The lifecycle verifies every file against the manifest, then copies them into its own versions directory.
+    const result = spawnSync(path.join(stage, "node"), [path.join(stage, "lifecycle.mjs"), lifecycle, ...args], { stdio: "inherit" });
+    if (result.error) throw result.error;
+    process.exitCode = result.status ?? 1;
+  } finally {
+    await fs.rm(stage, { recursive: true, force: true });
+  }
+}

package/package.json

@@ -1,47 +1,57 @@
-{
-  "name": "local-commander-agent",
-  "version": "0.3.44",
-  "description": "Windows companion for Local Commander: connect AI clients to local files, approved commands and localhost. Requires https://localcmd.app.",
-  "type": "module",
-  "bin": {
-    "localcommander": "bin/localcommander.mjs"
-  },
-  "os": [
-    "win32"
-  ],
-  "cpu": [
-    "x64"
-  ],
-  "engines": {
-    "node": ">=20.0.0"
-  },
-  "files": [
-    "bin/",
-    "runtime/",
-    "README.md",
-    "CHANGELOG.md"
-  ],
-  "scripts": {
-    "prepack": "node ../../scripts/build-npm-agent.mjs",
-    "prepublishOnly": "node ../../scripts/check-npm-publish-auth.mjs && node ../../scripts/verify-npm-agent.mjs"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "keywords": [
-    "mcp",
-    "local",
-    "agent",
-    "chatgpt",
-    "claude",
-    "windows"
-  ],
-  "localCommander": {
-    "controlPlaneOrigin": "https://localcmd.app"
-  },
-  "homepage": "https://localcmd.app",
-  "bugs": {
-    "url": "https://localcmd.app/support",
-    "email": "peter.mamrukov@localcmd.app"
-  }
-}
+{
+  "name": "local-commander-agent",
+  "version": "0.3.46",
+  "description": "Computer companion for Local Commander: connect AI clients to local files, approved commands and localhost. Requires https://localcmd.app.",
+  "type": "module",
+  "bin": {
+    "localcommander": "bin/localcommander.mjs"
+  },
+  "os": [
+    "win32",
+    "darwin",
+    "linux"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "optionalDependencies": {
+    "local-commander-agent-darwin-arm64": "0.3.46",
+    "local-commander-agent-linux-arm64": "0.3.46",
+    "local-commander-agent-linux-x64": "0.3.46"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "files": [
+    "bin/",
+    "runtime/",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "prepack": "node ../../scripts/build-npm-agent.mjs",
+    "prepublishOnly": "node ../../scripts/check-npm-publish-auth.mjs && node ../../scripts/verify-npm-agent.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "mcp",
+    "local",
+    "agent",
+    "chatgpt",
+    "claude",
+    "windows",
+    "macos",
+    "linux"
+  ],
+  "localCommander": {
+    "controlPlaneOrigin": "https://localcmd.app"
+  },
+  "homepage": "https://localcmd.app",
+  "bugs": {
+    "url": "https://localcmd.app/support",
+    "email": "peter.mamrukov@localcmd.app"
+  }
+}