@phnx-labs/agents-cli 1.20.6 → 1.20.7

package/dist/lib/platform/paths.js

@@ -0,0 +1,49 @@
+/**
+ * Path classification + normalization, platform-aware.
+ */
+import * as os from 'os';
+/** Windows drive-letter absolute path: `C:\` or `C:/`. */
+const WIN_DRIVE_RE = /^[a-zA-Z]:[\\/]/;
+/**
+ * Does this positional argument look like a filesystem path (vs a search term)?
+ *
+ * POSIX markers (`.`, `./`, `../`, `/`, `~`) are recognized on every platform —
+ * identical to the long-standing behavior. Windows-only shapes (drive-letter
+ * `C:\…`, UNC `\\…`, backslash-relative `.\` / `..\`) are recognized ONLY on
+ * win32, so a literal `C:\repo` typed on macOS/Linux still resolves as a search
+ * term — i.e. no behavior change off Windows.
+ */
+export function looksLikePath(query, platform = process.platform) {
+    if (query === '.' ||
+        query.startsWith('./') ||
+        query.startsWith('../') ||
+        query.startsWith('/') ||
+        query.startsWith('~')) {
+        return true;
+    }
+    if (platform === 'win32') {
+        return (WIN_DRIVE_RE.test(query) ||
+            query.startsWith('\\\\') ||
+            query.startsWith('.\\') ||
+            query.startsWith('..\\'));
+    }
+    return false;
+}
+/**
+ * Normalize a path for comparison/prefix-matching: backslashes folded to forward
+ * slashes and lowercased on Windows (its filesystem is case-insensitive). On
+ * POSIX the input is returned unchanged, so callers behave exactly as before.
+ */
+export function toComparablePath(p, platform = process.platform) {
+    if (platform === 'win32')
+        return p.replace(/\\/g, '/').toLowerCase();
+    return p;
+}
+/**
+ * Canonical home directory. Use this instead of `process.env.HOME`, which is
+ * unset on Windows (where the home is `USERPROFILE`); `os.homedir()` resolves
+ * correctly on all three platforms.
+ */
+export function homeDir() {
+    return os.homedir();
+}

package/dist/lib/platform/process.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Process liveness / control, platform-aware.
+ */
+/**
+ * Is a process with this PID currently alive?
+ *
+ * Uses the signal-0 probe, which is cross-platform in Node (Windows included —
+ * it maps to OpenProcess). Returns false on any error (no such process, or no
+ * permission to signal it), matching the long-standing call sites that treat a
+ * throw from `process.kill(pid, 0)` as "not running".
+ */
+export declare function isAlive(pid: number): boolean;

package/dist/lib/platform/process.js

@@ -0,0 +1,22 @@
+/**
+ * Process liveness / control, platform-aware.
+ */
+/**
+ * Is a process with this PID currently alive?
+ *
+ * Uses the signal-0 probe, which is cross-platform in Node (Windows included —
+ * it maps to OpenProcess). Returns false on any error (no such process, or no
+ * permission to signal it), matching the long-standing call sites that treat a
+ * throw from `process.kill(pid, 0)` as "not running".
+ */
+export function isAlive(pid) {
+    if (!pid || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/lib/pty-client.js

@@ -12,6 +12,7 @@ import * as path from 'path';
 import { getSocketPath, getPtyLogPath, isPtyServerRunning } from './pty-server.js';
 const CONNECT_TIMEOUT_MS = 5000;
 const RESPONSE_TIMEOUT_MS = 30000;
+const IS_WINDOWS = process.platform === 'win32';
 /**
  * Send a request to the PTY server and return the response.
  * Auto-starts the server if not running.
@@ -41,11 +42,13 @@ async function ensureServer() {
     });
     child.unref();
     fs.closeSync(logFd);
-    // Wait for socket to appear
+    // Wait for the server to become reachable. On Unix the socket file appearing is
+    // a cheap readiness signal; on Windows the named pipe is not a filesystem object
+    // (fs.existsSync always returns false), so we just attempt the ping directly.
     const socketPath = getSocketPath();
     const deadline = Date.now() + 5000;
     while (Date.now() < deadline) {
-        if (fs.existsSync(socketPath)) {
+        if (IS_WINDOWS || fs.existsSync(socketPath)) {
             // Verify we can connect
             try {
                 await sendRequest({ action: 'ping' });
@@ -70,9 +73,11 @@ function getServerSpawnArgs() {
         }
     }
     catch { }
-    // Fallback: use the globally installed agents command
+    // Fallback: use the globally installed agents command. `which` is Unix-only;
+    // Windows uses `where`, which can return multiple lines — take the first.
     try {
-        const agentsBin = execSync('which agents', { encoding: 'utf-8' }).trim();
+        const lookup = IS_WINDOWS ? 'where agents' : 'which agents';
+        const agentsBin = execSync(lookup, { encoding: 'utf-8' }).split(/\r?\n/)[0].trim();
         if (agentsBin) {
             return { bin: agentsBin, args: ['pty', '_server'] };
         }
@@ -86,7 +91,10 @@ function getServerSpawnArgs() {
 function sendRequest(req) {
     return new Promise((resolve, reject) => {
         const socketPath = getSocketPath();
-        if (!fs.existsSync(socketPath)) {
+        // On Unix a missing socket file means the server isn't up — fail fast with a
+        // clear message. On Windows the named pipe isn't a filesystem object, so we
+        // skip the probe and let createConnection surface ENOENT/connection errors.
+        if (!IS_WINDOWS && !fs.existsSync(socketPath)) {
             reject(new Error('PTY server socket not found. Is the server running?'));
             return;
         }

package/dist/lib/pty-server.d.ts

@@ -18,7 +18,30 @@
  * Returns null on any error so callers can skip the guard rather than crash.
  */
 export declare function captureProcessStartTime(pid: number): string | null;
-/** Get the unix socket path for the PTY server. */
+/**
+ * Wrap a user command so a `__SENTINEL__:<exit>` line is printed after it
+ * finishes — that line drives completion detection in the exec/read flow.
+ * The separator and exit-code variable are shell-family specific:
+ *   POSIX sh/zsh/bash : `cmd; echo "S:$?"`
+ *   PowerShell        : `cmd; echo "S:$LASTEXITCODE"`
+ *   cmd.exe           : `cmd & echo S:%errorlevel%`  (`&` always runs the echo)
+ * Only the completion marker matters; the numeric exit code is informational
+ * (the authoritative code comes from node-pty's onExit).
+ */
+export declare function buildSentinelCommand(shell: string, command: string): string;
+/**
+ * Resolve the IPC endpoint for a given platform + PTY scratch dir. Pure so both
+ * branches are testable without stubbing process.platform.
+ *
+ * Unix: an AF_UNIX socket file inside the scratch dir.
+ * Windows: a named pipe (`\\.\pipe\…`). Named pipes are NOT filesystem objects,
+ * so the name is derived from a hash of the (per-user) scratch dir to keep it
+ * stable across invocations and isolated per user — and callers must never probe
+ * it with fs.existsSync (it always reports false). Both forms are accepted by
+ * net.createServer/createConnection.
+ */
+export declare function derivePtyEndpoint(platform: NodeJS.Platform, ptyDir: string): string;
+/** Get the IPC endpoint the PTY server listens on / clients connect to. */
 export declare function getSocketPath(): string;
 /** Get the path to the PTY server PID file. */
 export declare function getPtyPidPath(): string;

package/dist/lib/pty-server.js

@@ -15,6 +15,7 @@ import * as crypto from 'crypto';
 import { execFileSync } from 'child_process';
 import { fileURLToPath } from 'url';
 import { getPtyDir as getPtyDirRoot } from './state.js';
+import { isAlive } from './platform/index.js';
 /**
  * Capture a stable identifier for a process at the moment it was started.
  * Used to defeat PID reuse: a kill(pid, ...) is only safe when the process
@@ -52,6 +53,7 @@ export function captureProcessStartTime(pid) {
     }
 }
 // --- Constants ---
+const IS_WINDOWS = process.platform === 'win32';
 const SENTINEL = '__AGENTS_PTY_DONE__';
 const SOCKET_NAME = 'pty.sock';
 const PID_FILE = 'pty.pid';
@@ -72,24 +74,81 @@ const PTY_ENV_ALLOWLIST = [
     'EDITOR', 'VISUAL', 'PAGER', 'LESS',
     'NO_COLOR', 'FORCE_COLOR',
 ];
+/**
+ * Windows allowlist. cmd.exe / PowerShell refuse to start (or misbehave) without
+ * SystemRoot, ComSpec, PATHEXT and the USERPROFILE/APPDATA family, so a Unix-style
+ * allowlist would spawn a broken shell. PATH/TERM/color/NODE vars are shared with
+ * the Unix list; the rest are Windows-specific.
+ */
+const PTY_ENV_ALLOWLIST_WIN = [
+    'SystemRoot', 'SystemDrive', 'windir', 'ComSpec', 'PATH', 'PATHEXT',
+    'TEMP', 'TMP', 'USERPROFILE', 'HOMEDRIVE', 'HOMEPATH', 'HOME',
+    'APPDATA', 'LOCALAPPDATA', 'PROGRAMFILES', 'PROGRAMDATA',
+    'USERNAME', 'USERDOMAIN', 'COMPUTERNAME', 'OS',
+    'PROCESSOR_ARCHITECTURE', 'NUMBER_OF_PROCESSORS',
+    'TERM', 'COLORTERM', 'NO_COLOR', 'FORCE_COLOR',
+    'NODE_PATH', 'BUN_INSTALL',
+];
 function buildPtyEnv() {
     const env = {};
-    for (const key of PTY_ENV_ALLOWLIST) {
+    const allowlist = IS_WINDOWS ? PTY_ENV_ALLOWLIST_WIN : PTY_ENV_ALLOWLIST;
+    for (const key of allowlist) {
         const v = process.env[key];
         if (v !== undefined)
             env[key] = v;
     }
     return env;
 }
+/**
+ * Wrap a user command so a `__SENTINEL__:<exit>` line is printed after it
+ * finishes — that line drives completion detection in the exec/read flow.
+ * The separator and exit-code variable are shell-family specific:
+ *   POSIX sh/zsh/bash : `cmd; echo "S:$?"`
+ *   PowerShell        : `cmd; echo "S:$LASTEXITCODE"`
+ *   cmd.exe           : `cmd & echo S:%errorlevel%`  (`&` always runs the echo)
+ * Only the completion marker matters; the numeric exit code is informational
+ * (the authoritative code comes from node-pty's onExit).
+ */
+export function buildSentinelCommand(shell, command) {
+    // Split on both separators: a Windows shell path (`C:\…\cmd.exe`) must be
+    // recognized even when this code runs under POSIX path.basename, which does
+    // not treat `\` as a separator.
+    const name = (shell.split(/[\\/]/).pop() || shell).toLowerCase();
+    if (name === 'cmd.exe' || name === 'cmd') {
+        return `${command} & echo ${SENTINEL}:%errorlevel%`;
+    }
+    if (name === 'powershell.exe' || name === 'powershell' || name === 'pwsh.exe' || name === 'pwsh') {
+        return `${command}; echo "${SENTINEL}:$LASTEXITCODE"`;
+    }
+    return `${command}; echo "${SENTINEL}:$?"`;
+}
 /** Get the PTY helper directory, creating it if needed. */
 function getPtyDir() {
     const dir = getPtyDirRoot();
     fs.mkdirSync(dir, { recursive: true });
     return dir;
 }
-/** Get the unix socket path for the PTY server. */
+/**
+ * Resolve the IPC endpoint for a given platform + PTY scratch dir. Pure so both
+ * branches are testable without stubbing process.platform.
+ *
+ * Unix: an AF_UNIX socket file inside the scratch dir.
+ * Windows: a named pipe (`\\.\pipe\…`). Named pipes are NOT filesystem objects,
+ * so the name is derived from a hash of the (per-user) scratch dir to keep it
+ * stable across invocations and isolated per user — and callers must never probe
+ * it with fs.existsSync (it always reports false). Both forms are accepted by
+ * net.createServer/createConnection.
+ */
+export function derivePtyEndpoint(platform, ptyDir) {
+    if (platform === 'win32') {
+        const hash = crypto.createHash('sha1').update(ptyDir).digest('hex').slice(0, 16);
+        return `\\\\.\\pipe\\agents-pty-${hash}`;
+    }
+    return path.join(ptyDir, SOCKET_NAME);
+}
+/** Get the IPC endpoint the PTY server listens on / clients connect to. */
 export function getSocketPath() {
-    return path.join(getPtyDir(), SOCKET_NAME);
+    return derivePtyEndpoint(process.platform, getPtyDir());
 }
 /** Get the path to the PTY server PID file. */
 export function getPtyPidPath() {
@@ -109,16 +168,17 @@ export function isPtyServerRunning() {
         const pid = parseInt(fs.readFileSync(pidPath, 'utf-8').trim(), 10);
         if (isNaN(pid))
             return false;
-        process.kill(pid, 0);
-        return true;
+        if (isAlive(pid))
+            return true;
     }
     catch {
-        try {
-            fs.unlinkSync(pidPath);
-        }
-        catch { }
-        return false;
+        // read failed — fall through and treat the pid file as stale
     }
+    try {
+        fs.unlinkSync(pidPath);
+    }
+    catch { }
+    return false;
 }
 // --- Logging ---
 function rotateLogsIfNeeded(logPath) {
@@ -221,8 +281,10 @@ export async function runPtyServer() {
         fs.unlinkSync(pidPath);
     }
     catch { } });
-    // Remove stale socket from a prior crashed server. Safe now that we hold the PID slot.
-    if (fs.existsSync(socketPath)) {
+    // Remove stale socket from a prior crashed server. Safe now that we hold the PID
+    // slot. Windows named pipes are not filesystem inodes — they vanish with their
+    // owning process, so there's nothing to unlink (and existsSync always reports false).
+    if (!IS_WINDOWS && fs.existsSync(socketPath)) {
         try {
             fs.unlinkSync(socketPath);
         }
@@ -286,8 +348,10 @@ export async function runPtyServer() {
             case 'start': {
                 const rows = req.params?.rows || 24;
                 const cols = req.params?.cols || 120;
-                const shell = req.params?.shell || process.env.SHELL || 'zsh';
-                const cwd = req.params?.cwd || process.env.HOME || '/';
+                const shell = req.params?.shell
+                    || (IS_WINDOWS ? (process.env.ComSpec || 'powershell.exe') : (process.env.SHELL || 'zsh'));
+                const cwd = req.params?.cwd
+                    || (IS_WINDOWS ? (process.env.USERPROFILE || process.env.HOME || process.cwd()) : (process.env.HOME || '/'));
                 const id = generateId();
                 let ptyProcess;
                 try {
@@ -358,7 +422,9 @@ export async function runPtyServer() {
                 session.appActive = true;
                 session.activeCommand = command;
                 session.pendingOutput = '';
-                session.pty.write(`${command}; echo "${SENTINEL}:$?"\n`);
+                // Windows conpty submits on CR; POSIX line discipline expects LF.
+                const submit = IS_WINDOWS ? '\r' : '\n';
+                session.pty.write(`${buildSentinelCommand(session.shell, command)}${submit}`);
                 session.lastActivity = Date.now();
                 return { ok: true, submitted: true };
             }
@@ -525,20 +591,28 @@ export async function runPtyServer() {
     // any local user with execute on the parent dir could connect to the socket
     // during the listen()-to-chmod() window. macOS BSD AF_UNIX semantics make
     // socket mode advisory only, so the parent dir is the real boundary.
+    //
+    // On Windows the transport is a named pipe, not a filesystem inode: chmod/umask
+    // are no-ops (and umask throws in some Node builds), and pipe ACLs default to
+    // the creating user. So we skip the Unix hardening entirely there.
     const agentsDir = getPtyDirRoot();
     fs.mkdirSync(agentsDir, { recursive: true });
-    fs.chmodSync(agentsDir, 0o700);
-    // umask covers any inherited group/other bits while listen() is creating
-    // the socket inode — it only matters for the unobservable instant before
-    // we can chmod the inode itself.
-    process.umask(0o077);
+    if (!IS_WINDOWS) {
+        fs.chmodSync(agentsDir, 0o700);
+        // umask covers any inherited group/other bits while listen() is creating
+        // the socket inode — it only matters for the unobservable instant before
+        // we can chmod the inode itself.
+        process.umask(0o077);
+    }
     await new Promise((resolve) => {
         server.listen(socketPath, () => resolve());
     });
     // Surface chmod failures: a 0o600 socket is a load-bearing security
     // assumption, not a nice-to-have. If we can't lock it down, refuse to
-    // start so the caller learns immediately.
-    fs.chmodSync(socketPath, 0o600);
+    // start so the caller learns immediately. (No-op on Windows named pipes.)
+    if (!IS_WINDOWS) {
+        fs.chmodSync(socketPath, 0o600);
+    }
     log('INFO', `PTY server started (PID: ${process.pid}, socket: ${socketPath})`);
     // Shutdown handler
     function shutdown() {
@@ -549,10 +623,13 @@ export async function runPtyServer() {
         sessions.clear();
         clearInterval(cleanupInterval);
         server.close();
-        try {
-            fs.unlinkSync(socketPath);
+        // Named pipes are reclaimed by the OS on close; only Unix sockets leave a file.
+        if (!IS_WINDOWS) {
+            try {
+                fs.unlinkSync(socketPath);
+            }
+            catch { }
         }
-        catch { }
         try {
             fs.unlinkSync(getPtyPidPath());
         }

package/dist/lib/session/artifacts.js

@@ -8,6 +8,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { parseSession } from './parse.js';
+import { toComparablePath } from '../platform/index.js';
 /** Tool names that produce file artifacts (writes, edits, patches). */
 const WRITE_TOOLS = new Set([
     'Write', 'Edit', 'write_file', 'edit_file', 'create_file', 'replace', 'patch',
@@ -87,8 +88,13 @@ export function resolveArtifact(artifacts, name) {
         return byBase[0];
     if (byBase.length > 1)
         return byBase[0];
-    // Path suffix match (e.g. "src/foo.ts")
-    const bySuffix = artifacts.filter(a => a.path.endsWith('/' + name) || a.path === name);
+    // Path suffix match (e.g. "src/foo.ts"). Normalize so Windows `\` paths match
+    // a forward-slash query too; on POSIX this is identical to the old comparison.
+    const target = toComparablePath(name);
+    const bySuffix = artifacts.filter(a => {
+        const ap = toComparablePath(a.path);
+        return ap.endsWith('/' + target) || ap === target;
+    });
     if (bySuffix.length >= 1)
         return bySuffix[0];
     return null;

package/dist/lib/shims.js

@@ -13,6 +13,7 @@ import * as path from 'path';
 import * as os from 'os';
 import { fileURLToPath } from 'url';
 import { confirm, select } from '@inquirer/prompts';
+import { IS_WINDOWS } from './platform/index.js';
 import { getShimsDir, getVersionsDir, getBackupsDir, ensureAgentsDir } from './state.js';
 export { getShimsDir };
 import { AGENTS } from './agents.js';
@@ -521,8 +522,28 @@ export function createShim(agent) {
     const shimPath = path.join(shimsDir, agentConfig.cliCommand);
     const script = generateShimScript(agent);
     fs.writeFileSync(shimPath, script, { mode: 0o755 });
+    // Windows can't execute the bash shim directly. Drop a `.cmd` companion next
+    // to it that delegates to the node-side transparent resolver (`agents __shim`),
+    // so the version resolution stays single-sourced instead of reimplemented in batch.
+    if (IS_WINDOWS) {
+        writeWindowsCmdShim(shimPath + '.cmd', agentConfig.cliCommand);
+    }
     return shimPath;
 }
+/**
+ * Generate a Windows `.cmd` launcher that delegates to `agents __shim <spec>`.
+ * `spec` is the agent's cliCommand for the default-version shim, or
+ * `cliCommand@version` for a versioned alias. node + the dist entrypoint are
+ * resolved at generation time so the launcher does not depend on `agents`
+ * already being on PATH.
+ */
+function writeWindowsCmdShim(cmdPath, spec) {
+    const indexJs = getAgentsBinForGeneratedShim();
+    const content = `@echo off\r\n` +
+        `rem Auto-generated by agents-cli - do not edit\r\n` +
+        `node "${indexJs}" __shim ${spec} %*\r\n`;
+    fs.writeFileSync(cmdPath, content);
+}
 /**
  * Remove the shim for an agent.
  */
@@ -532,6 +553,12 @@ export function removeShim(agent) {
     const shimPath = path.join(shimsDir, agentConfig.cliCommand);
     if (fs.existsSync(shimPath)) {
         fs.unlinkSync(shimPath);
+        if (IS_WINDOWS) {
+            try {
+                fs.unlinkSync(shimPath + '.cmd');
+            }
+            catch { }
+        }
         return true;
     }
     return false;
@@ -682,6 +709,9 @@ export function createVersionedAlias(agent, version) {
     const aliasPath = path.join(shimsDir, `${agentConfig.cliCommand}@${version}`);
     const script = generateVersionedAliasScript(agent, version);
     fs.writeFileSync(aliasPath, script, { mode: 0o755 });
+    if (IS_WINDOWS) {
+        writeWindowsCmdShim(aliasPath + '.cmd', `${agentConfig.cliCommand}@${version}`);
+    }
     return aliasPath;
 }
 /**
@@ -693,6 +723,12 @@ export function removeVersionedAlias(agent, version) {
     const aliasPath = path.join(shimsDir, `${agentConfig.cliCommand}@${version}`);
     if (fs.existsSync(aliasPath)) {
         fs.unlinkSync(aliasPath);
+        if (IS_WINDOWS) {
+            try {
+                fs.unlinkSync(aliasPath + '.cmd');
+            }
+            catch { }
+        }
         return true;
     }
     return false;
@@ -1488,6 +1524,15 @@ Then restart your shell or run:
  * Returns true if added, false if already present or failed.
  */
 export function addShimsToPath(overrides) {
+    // Windows has no shell rc file to edit: the primary `agents` command is already
+    // on PATH via npm's global bin, and bare shorthands / versioned aliases are
+    // handled by the `.cmd` shims plus the PATH guidance printed at install time.
+    // Report "already present" so callers don't emit a misleading "added to
+    // ~/.bashrc / source ~/.bashrc" message. (The `shell` override is the test hook
+    // for exercising the POSIX path, so it bypasses this short-circuit.)
+    if (IS_WINDOWS && !overrides?.shell) {
+        return { success: true, alreadyPresent: true };
+    }
     const shimsDir = overrides?.shimsDir || getShimsDir();
     const { rcFile, rcPath, shell } = getShellRcFile(overrides);
     // Read current rc file content

package/dist/lib/teams/agents.js

@@ -14,6 +14,7 @@ import * as path from 'path';
 import * as os from 'os';
 import { randomUUID } from 'crypto';
 import { resolveAgentsDir } from './persistence.js';
+import { findExecutable } from '../platform/index.js';
 import { normalizeEvents } from './parsers.js';
 import { debug } from './debug.js';
 import { setGeminiAutoUpdateDisabled, updateGeminiSettings } from '../gemini-settings.js';
@@ -300,13 +301,10 @@ export function checkCliAvailable(agentType) {
     if (!executable) {
         return [false, `Unknown agent type: ${agentType}`];
     }
-    try {
-        const whichPath = execFileSync('which', [executable], { encoding: 'utf-8' }).trim();
-        return [true, whichPath];
-    }
-    catch {
-        return [false, `CLI tool '${executable}' not found in PATH. Install it first.`];
-    }
+    const resolved = findExecutable(executable);
+    return resolved
+        ? [true, resolved]
+        : [false, `CLI tool '${executable}' not found in PATH. Install it first.`];
 }
 /** Check availability of all known agent CLIs. Returns a map of agent type to install status. */
 export function checkAllClis() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.6",
+  "version": "1.20.7",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",

package/scripts/postinstall.js

@@ -95,6 +95,11 @@ function writeAliasShims() {
     const target = path.join(SHIMS_DIR, name);
     const script = `#!/bin/sh\nAGENTS_BIN=${shellQuote(AGENTS_BIN)}\nif [ -z "$AGENTS_BIN" ] || [ ! -x "$AGENTS_BIN" ]; then\n  echo "agents: agents-cli entrypoint missing or not executable: $AGENTS_BIN" >&2\n  exit 127\nfi\nexec "$AGENTS_BIN" ${name} "$@"\n`;
     fs.writeFileSync(target, script, { mode: 0o755 });
+    // Windows can't run the POSIX shim; drop a `.cmd` companion that invokes the
+    // entrypoint via node so the bare shorthand works in a Windows shell.
+    if (process.platform === 'win32') {
+      fs.writeFileSync(target + '.cmd', `@echo off\r\nnode "${AGENTS_BIN}" ${name} %*\r\n`);
+    }
     written.push(name);
   }
   return written;
@@ -139,8 +144,20 @@ function isAlreadyConfigured(rcFile) {
 }
 
 async function main() {
+  // Windows has no shell rc files to edit. Write the `.cmd` shorthands and point
+  // the user at the PATH entry they can add (the primary `agents` command is
+  // already on PATH via npm's global bin, so this only affects bare shorthands
+  // and versioned aliases).
+  if (process.platform === 'win32') {
+    console.log(`\nagents-cli installed.`);
+    const written = writeAliasShims();
+    console.log(`  Installed shorthands: ${written.join(', ')}`);
+    console.log(`\nTo use bare shorthands (${ALIASES.join(', ')}) and versioned aliases, add this to your PATH:`);
+    console.log(`  ${SHIMS_DIR}`);
+    console.log(`  PowerShell: setx PATH "$env:PATH;${SHIMS_DIR}"  (then open a new terminal)`);
+  }
   // Opt-in: AGENTS_INIT_SHELL=1 npm install -g @phnx-labs/agents-cli
-  if (process.env.AGENTS_INIT_SHELL === '1') {
+  else if (process.env.AGENTS_INIT_SHELL === '1') {
     const rcFile = getShellRc();
     if (!isAlreadyConfigured(rcFile)) {
       const addition = `\n# agents-cli: version switching for AI coding agents\n${exportLine}\n`;