eimexdev · eimexdev · Sep 11, 2026 · Sep 11, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -4,7 +4,10 @@ permissions:
   contents: read
 jobs:
   test:
-    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4

diff --git a/README.md b/README.md
@@ -21,7 +21,7 @@ The [agent setup guide](docs/agent-setup.md) covers discovery, credentials, conf
 
 ## Manual setup
 
-You need Linux, Node.js 24.10+, GitHub CLI signed in, and a compatible T3 server. Build this checkout and add one MCP configuration entry. The first thread-listing or watch call finds local T3 and creates its credential. Follow the [manual steps](docs/setup.md).
+You need macOS or Linux, Node.js 24.10+, GitHub CLI signed in, and a compatible T3 server. Build this checkout and add one MCP configuration entry. The first thread-listing or watch call finds local T3 and creates its credential. Follow the [manual steps](docs/setup.md).
 
 No URL or token settings are needed for a standard local installation. If multiple instances are found, select one with `T3POLL_BASE_DIR`. Choose the destination thread when registering each watch.
 

diff --git a/docs/agent-setup.md b/docs/agent-setup.md
@@ -4,7 +4,7 @@ Use this guide when asked to install or configure t3poll. For updates, follow [R
 
 Keep the running T3 server and ongoing conversations intact. Setup creates a credential but does not require a watch, a test message, or a T3 restart.
 
-1. Reuse an existing checkout of `https://github.com/eimexdev/t3poll`, or choose a suitable installation directory. Follow [installation](setup.md#install). Verify Node and authenticated GitHub CLI are available to the MCP process. Build successfully before configuring it.
+1. Reuse an existing checkout of `https://github.com/eimexdev/t3poll`, or choose a suitable installation directory. Follow [installation](setup.md#install). Verify Node and authenticated GitHub CLI are available to the MCP process. On macOS, use an absolute Node runtime path and include the GitHub CLI installation directory in the MCP PATH when needed. A running packaged T3 desktop app is supported without installing a separate T3 CLI. Build successfully before configuring it.
 2. Add the minimal entry from [MCP registration](setup.md#register-mcp) to the Codex configuration home used by T3's provider. Preserve unrelated entries. Use absolute executable/script paths where needed. Existing explicit credentials can remain configured; they stay user-managed. A new standard installation needs no connection variables.
 3. Run [verification](setup.md#verify). `list` with `threads=true` automatically discovers T3 and creates a credential. If discovery reports multiple instances, ask the user to select the reported home and set `T3POLL_BASE_DIR`. For unsupported layouts, follow [manual overrides](setup.md#select-an-instance-or-use-manual-credentials). Do not guess the destination conversation.
 4. Verify the client exposes `watch`, `list`, and `stop` after a reconnect or new provider session. Preserve ongoing work while it loads. Report the installation directory, changed config file, and verification result. If only the CLI was tested, say that MCP verification is still pending.

diff --git a/docs/compatibility.md b/docs/compatibility.md
@@ -4,7 +4,7 @@ t3poll targets the authenticated orchestration API in stock T3 Code v0.0.40. It
 
 Verified September 11, 2026 on Node 24.21.0 and Linux: the stock-release proof passed with T3 0.0.40 and a scripted Codex provider. MCP disconnected before delivery; T3 recorded the notification, invoked the provider, completed the turn, and deduplicated a repeated command. A separate read-only GitHub smoke check parsed reviews, comments, and checks from a public upstream PR. No live T3 server or real model session was used.
 
-The initial platform is Linux with Node.js 24.10+. The implementation uses Node's built-in SQLite, the MCP SDK, and Zod. It does not require Effect or a database server. MCP uses ordinary stdio tools; Tasks and unsolicited MCP wakeups are not dependencies.
+Supported platforms are macOS and Linux with Node.js 24.10+. The implementation uses Node's built-in SQLite, the MCP SDK, and Zod. It does not require Effect or a database server. MCP uses ordinary stdio tools; Tasks and unsolicited MCP wakeups are not dependencies.
 
 ## Boundaries
 
@@ -48,4 +48,14 @@ This proves the protocol and process flow without spending model tokens. It does
 
 Tested against an isolated copy of T3 `0.0.41-nightly.20260910.1507` on Linux. The proof starts MCP without URL/token configuration, discovers the instance, creates and verifies its credential, and forces credential renewal from the detached worker before a second delivery. A fresh CLI process then reuses the connection. No running user server or real model is used.
 
-Unit/process tests additionally cover simultaneous first use across processes, expired credential replacement, failed issuance/verification preserving the token, stale process state, ambiguous instances, and manual credential overrides. Discovery requires Linux `/proc` and an installed T3 `dist/bin.mjs` process with `userdata` runtime state. Other layouts retain the manual connection path.
+Unit/process tests additionally cover simultaneous first use across processes, expired credential replacement, failed issuance/verification preserving the token, stale process state, ambiguous instances, and manual credential overrides. Discovery supports Linux `/proc` and macOS native process inspection for installed T3 `dist/bin.mjs` processes with `userdata` runtime state. Packaged macOS desktop apps use their bundled Electron runtime for credential issuance and renewal. Other layouts retain the manual connection path.
+
+## macOS verification
+
+Verified September 11, 2026 on Apple Silicon with Node 24.21.0 and T3 Code Nightly `0.0.41-nightly.20260910.1507`. All 30 automated tests pass, including process discovery, paths containing spaces, symlinks, credential renewal, and worker survival after MCP exit. CI runs the suite on both Ubuntu and macOS. Intel Macs have not been tested locally.
+
+A read-only check of a running desktop installation discovered its server without connection overrides, issued a managed credential, and listed 142 threads through both the service and a real stdio MCP client. The MCP client exposed `watch`, `list`, and `stop`. The live installation had no watches, and no messages or watches were created there.
+
+The isolated stock proof passed against the same packaged app. It verified initial credential issuance, renewal from the detached worker, delivery after MCP disconnected, another delivery during a running scripted provider turn, turn completion, and command deduplication. No model calls were made. The proof pins the scripted provider's executable and environment because desktop startup can replace the inherited PATH.
+
+The stock proof also accepts a packaged macOS app. Use the app's executable as `T3POLL_TEST_T3_RUNTIME` and its `Contents/Resources/app.asar/apps/server/dist/bin.mjs` as `T3POLL_TEST_T3_BIN`. The proof selects only its disposable T3 home, so another running installation cannot be selected by accident.
diff --git a/docs/setup.md b/docs/setup.md
@@ -1,6 +1,6 @@
 # Manual setup
 
-Requires Linux, Node.js 24.10+, [GitHub CLI](https://cli.github.com/) signed in, and a running local T3 installation. Nothing is published to npm yet.
+Requires macOS or Linux, Node.js 24.10+, [GitHub CLI](https://cli.github.com/) signed in, and a running local T3 installation. Nothing is published to npm yet.
 
 ## Install
 
@@ -25,7 +25,14 @@ command = "node"
 args = ["/absolute/path/to/t3poll/dist/cli.js", "mcp"]
 ```
 
-Use an absolute Node path if the provider's PATH differs from your terminal. Load the entry in a new provider session or reconnect MCP. T3 itself does not need restarting.
+Use an absolute Node path if the provider's PATH differs from your terminal. This is common with macOS desktop apps and Node version managers. `node -p process.execPath` prints the runtime path. GitHub CLI must also be on the MCP process's PATH. For Homebrew on Apple Silicon, an example is:
+
+```toml
+[mcp_servers.t3poll.env]
+PATH = "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
+```
+
+Merge optional settings into this same environment table. Load the entry in a new provider session or reconnect MCP. T3 itself does not need restarting.
 
 ## Verify
 
@@ -41,7 +48,9 @@ Ask the agent to watch a PR and select its destination thread. Thread selection
 
 ## Automatic connection
 
-Discovery checks `T3CODE_HOME`, or `~/.t3` by default, and `.t3` directories in the current directory and its parents. It reads `userdata/server-runtime.json` and verifies the live process, its owner, installed T3 CLI, and data directory. Stale files are ignored.
+Discovery checks `T3CODE_HOME`, or `~/.t3` by default, and `.t3` directories in the current directory and its parents. It reads `userdata/server-runtime.json` and verifies the live process, its owner, installed T3 CLI, and data directory. Linux uses `/proc`. macOS reads exact process arguments through native system APIs, using the bundled Koffi dependency, and uses the system `ps` and `lsof` commands for ownership and file checks. Paths containing spaces and symlinked installations are supported.
+
+On macOS, the packaged T3 Code desktop app is also supported. t3poll locates its bundled server and runs its auth CLI through Electron in Node mode. It checks that the server has the selected home's `userdata/state.sqlite` open, since desktop bootstrap can pass the home through a pipe. No separate global `t3` installation is needed. Stale files are ignored.
 
 The matching T3 CLI issues a 30-day credential. t3poll verifies it before saving it with owner-only permissions under `T3POLL_HOME/credentials`. It replaces managed credentials on use within one day of expiration, or after expiration. MCP and the worker coordinate replacement across processes. Failed replacement preserves the previous token and continues using it until expiration, retrying renewal after five minutes; no other service needs to run. Previous successfully used sessions expire naturally. A newly issued session that fails verification is revoked. Failed revocation is recorded and retried before issuing another session.
 
@@ -58,7 +67,7 @@ T3POLL_BASE_DIR = "/absolute/path/to/t3-home"
 
 `T3POLL_URL` can also select a discovered instance by origin. Credentials for different homes/origins are stored separately. Saved watches stay attached to their original origin; a server port change requires registering the watch again.
 
-Automatic setup supports installed T3 Node CLI processes with the `userdata` layout. Source runners, the older `dev` layout, and remote connections use explicit settings instead:
+Automatic setup supports installed T3 Node CLI processes on macOS and Linux, and packaged macOS T3 desktop apps, with the `userdata` layout. Source runners, the older `dev` layout, and remote connections use explicit settings instead:
 
 ```toml
 [mcp_servers.t3poll.env]