start-ai-cli 0.1.0 → 0.1.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,41 +1,63 @@
-# start-ai-cli
+# start-ai-cli - AI coding CLI launcher
 
-Open Codex CLI, Claude Code, and Cursor CLI from the current directory in one Windows Terminal window.
+[![npm version](https://img.shields.io/npm/v/start-ai-cli.svg)](https://www.npmjs.com/package/start-ai-cli)
+[![npm downloads](https://img.shields.io/npm/dm/start-ai-cli.svg)](https://www.npmjs.com/package/start-ai-cli)
+[![license: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
-## Requirements
+`start-ai-cli` is an npm package and command line tool for launching multiple AI coding CLIs from the same project directory. It opens Codex CLI, Claude Code, and Cursor CLI in separate terminal tabs or windows so every assistant starts in the current workspace.
 
-- Windows
-- Node.js 18 or newer
-- Windows Terminal available as `wt.exe`
-- Codex CLI available as `codex`
-- Claude Code CLI available as `claude`
-- Cursor CLI available as `agent`
+Use it when you want one command to start your AI coding agents:
+
+```bash
+npx start-ai-cli
+```
+
+## Features
+
+- Launches Codex CLI, Claude Code CLI, and Cursor CLI from the current directory.
+- Opens each available tool in its own Windows Terminal tab or macOS Terminal window.
+- Skips missing CLIs instead of failing when at least one supported tool is available.
+- Works as a global npm command or one-off `npx` command.
+- Has no runtime dependencies.
 
 ## Install
 
+Run without installing:
+
 ```bash
-npm install -g start-ai-cli
+npx start-ai-cli
 ```
 
-For local development from this directory:
+Install globally:
 
 ```bash
-npm link
+npm install -g start-ai-cli
 ```
 
-## Usage
-
-Run the command from the project directory you want both tools to use:
+Then run it from the project directory you want the AI tools to use:
 
 ```bash
 start-ai-cli
 ```
 
-It opens Windows Terminal with three tabs:
+## Supported Tools
 
-- `Codex`, running `codex`
-- `Claude`, running `claude`
-- `Cursor`, running `agent`
+| Tool | Required command | Terminal title |
+| --- | --- | --- |
+| Codex CLI | `codex` | `Codex` |
+| Claude Code | `claude` | `Claude` |
+| Cursor CLI | `agent` | `Cursor` |
+
+On Windows, `start-ai-cli` uses Windows Terminal (`wt.exe`) with PowerShell. On macOS, it uses Terminal.app through `osascript`.
+
+## Requirements
+
+- Windows or macOS
+- Node.js 18 or newer
+- Windows Terminal available as `wt.exe` on Windows
+- PowerShell 7 available as `pwsh.exe`, or Windows PowerShell, on Windows
+- Terminal.app and `osascript` available on macOS
+- At least one supported AI coding CLI available in `PATH`
 
 ## Options
 
@@ -44,6 +66,30 @@ start-ai-cli --help
 start-ai-cli --version
 ```
 
+## Troubleshooting
+
+### `start-ai-cli cannot start: no CLI tools found in PATH`
+
+Install or expose at least one supported command in your shell:
+
+- `codex` for Codex CLI
+- `claude` for Claude Code
+- `agent` for Cursor CLI
+
+### Windows Terminal was not found
+
+Install Windows Terminal and make sure `wt.exe` is available in `PATH`.
+
+### PowerShell was not found
+
+Install PowerShell 7 (`pwsh.exe`) or make sure Windows PowerShell (`powershell.exe`) is available.
+
+## Package Links
+
+- npm package: https://www.npmjs.com/package/start-ai-cli
+- GitHub repository: https://github.com/guoxiao0521/open-ai-cli
+- Issues: https://github.com/guoxiao0521/open-ai-cli/issues
+
 ## Development
 
 ```bash
@@ -54,6 +100,8 @@ npm run publish:dry-run
 
 ## Publish
 
+`README.md` and npm metadata changes appear on npm after publishing a new package version.
+
 ```bash
 npm login --registry=https://registry.npmjs.org/
 npm publish

package/bin/start-ai-cli.js

@@ -1,170 +1,269 @@
 #!/usr/bin/env node
-
-import { spawn, spawnSync } from 'node:child_process';
-import { readFileSync, realpathSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const COMMAND = 'start-ai-cli';
-
-const REQUIRED_COMMANDS = [
-  { command: 'wt.exe', label: 'Windows Terminal (wt.exe)' },
-  { command: 'codex', label: 'Codex CLI (codex)' },
-  { command: 'claude', label: 'Claude Code CLI (claude)' },
-  { command: 'agent', label: 'Cursor CLI (agent)' }
+
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { dirname, resolve, win32 as pathWin32 } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const COMMAND = 'start-ai-cli';
+
+const HARD_REQUIREMENTS_BY_PLATFORM = {
+  win32: [{ command: 'wt.exe', label: 'Windows Terminal (wt.exe)' }],
+  darwin: [{ command: 'osascript', label: 'AppleScript runner (osascript)' }]
+};
+
+const CLI_COMMANDS = [
+  { command: 'codex', label: 'Codex CLI (codex)', title: 'Codex' },
+  { command: 'claude', label: 'Claude Code CLI (claude)', title: 'Claude' },
+  { command: 'agent', label: 'Cursor CLI (agent)', title: 'Cursor' }
 ];
 
-const HELP_TEXT = `Usage:
-  ${COMMAND}
-  ${COMMAND} --help
-  ${COMMAND} --version
-
-Opens Windows Terminal with three tabs in the current directory:
-  - Codex: runs "codex"
-  - Claude: runs "claude"
-  - Cursor: runs "agent"
-
+const DEFAULT_WINDOWS_SHELL_COMMAND = 'pwsh.exe';
+
+const HELP_TEXT = `Usage:
+  ${COMMAND}
+  ${COMMAND} --help
+  ${COMMAND} --version
+
+Opens terminal tabs/windows in the current directory:
+  - Codex: runs "codex"
+  - Claude: runs "claude"
+  - Cursor: runs "agent"
+
 Requirements:
-  - Windows
-  - Windows Terminal (wt.exe)
+  - Windows with Windows Terminal (wt.exe) and PowerShell, or macOS with Terminal.app
   - Codex CLI available as "codex"
   - Claude Code CLI available as "claude"
   - Cursor CLI available as "agent"
-`;
-
-export function parseArgs(args) {
-  if (args.includes('--help') || args.includes('-h')) {
-    return { action: 'help' };
-  }
-
-  if (args.includes('--version') || args.includes('-v')) {
-    return { action: 'version' };
+`;
+
+export function parseArgs(args) {
+  if (args.includes('--help') || args.includes('-h')) {
+    return { action: 'help' };
+  }
+
+  if (args.includes('--version') || args.includes('-v')) {
+    return { action: 'version' };
+  }
+
+  const unknown = args.filter((arg) => arg.startsWith('-'));
+  if (unknown.length > 0) {
+    return { action: 'error', message: `Unknown option: ${unknown.join(', ')}` };
+  }
+
+  return { action: 'open' };
+}
+
+export function getPackageVersion() {
+  const packageJsonPath = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+  const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+  return packageJson.version;
+}
+
+export function buildWtArgs({ cwd, tabs, shellCommand = DEFAULT_WINDOWS_SHELL_COMMAND }) {
+  const result = [];
+  for (let i = 0; i < tabs.length; i++) {
+    if (i > 0) result.push(';');
+    result.push(
+      'new-tab',
+      '--title',
+      tabs[i].title,
+      '-d',
+      cwd,
+      shellCommand,
+      '-NoExit',
+      '-ExecutionPolicy',
+      'Bypass',
+      '-Command',
+      tabs[i].command
+    );
   }
-
-  const unknown = args.filter((arg) => arg.startsWith('-'));
-  if (unknown.length > 0) {
-    return { action: 'error', message: `Unknown option: ${unknown.join(', ')}` };
-  }
-
-  return { action: 'open' };
-}
-
-export function getPackageVersion() {
-  const packageJsonPath = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
-  const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
-  return packageJson.version;
-}
-
-export function buildWtArgs({ cwd, codexCommand = 'codex', claudeCommand = 'claude', cursorCommand = 'agent' }) {
-  return [
-    'new-tab',
-    '--title',
-    'Codex',
-    '-d',
-    cwd,
-    'powershell.exe',
-    '-NoExit',
-    '-Command',
-    codexCommand,
-    ';',
-    'new-tab',
-    '--title',
-    'Claude',
-    '-d',
-    cwd,
-    'powershell.exe',
-    '-NoExit',
-    '-Command',
-    claudeCommand,
-    ';',
-    'new-tab',
-    '--title',
-    'Cursor',
-    '-d',
-    cwd,
-    'powershell.exe',
-    '-NoExit',
-    '-Command',
-    cursorCommand
-  ];
+  return result;
 }
-
-export function commandExists(command, { env = process.env } = {}) {
-  const result = spawnSync('where.exe', [command], {
-    env,
-    stdio: 'ignore',
-    windowsHide: true
-  });
+
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", "'\\''")}'`;
+}
+
+function appleScriptQuote(value) {
+  return JSON.stringify(String(value));
+}
+
+export function buildMacTerminalScript({ cwd, tabs }) {
+  const commands = tabs.map(({ command }) => `cd ${shellQuote(cwd)} && ${command}`);
+  const lines = [
+    'tell application "Terminal"',
+    '  activate'
+  ];
+
+  for (const command of commands) {
+    lines.push(`  do script ${appleScriptQuote(command)}`);
+  }
+
+  lines.push('end tell');
+  return lines.join('\n');
+}
+
+export function buildMacTerminalArgs({ cwd, tabs }) {
+  return ['-e', buildMacTerminalScript({ cwd, tabs })];
+}
+
+export function commandExists(command, { env = process.env, platform = process.platform } = {}) {
+  const executable = platform === 'win32' ? 'where.exe' : 'sh';
+  const args = platform === 'win32'
+    ? [command]
+    : ['-lc', `command -v ${shellQuote(command)}`];
+
+  const result = spawnSync(executable, args, {
+    env,
+    stdio: 'ignore',
+    windowsHide: true
+  });
 
   return result.status === 0;
 }
 
-export function getMissingRequirements({ platform = process.platform, env = process.env } = {}) {
-  if (platform !== 'win32') {
-    return ['Windows is required.'];
+function getSystemWindowsPowerShellPath(env = process.env) {
+  const systemRoot = env.SystemRoot ?? env.SYSTEMROOT ?? env.windir ?? env.WINDIR;
+  if (!systemRoot) {
+    return null;
   }
 
-  return REQUIRED_COMMANDS
-    .filter(({ command }) => !commandExists(command, { env }))
-    .map(({ label }) => `${label} was not found in PATH.`);
-}
-
-export function launchTerminals({ cwd = process.cwd(), env = process.env } = {}) {
-  const child = spawn('wt.exe', buildWtArgs({ cwd }), {
-    cwd,
-    env,
-    detached: true,
-    stdio: 'ignore',
-    windowsHide: false
-  });
-
-  child.unref();
+  return pathWin32.join(systemRoot, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
 }
 
-export function main(args = process.argv.slice(2), options = {}) {
-  const parsed = parseArgs(args);
-
-  if (parsed.action === 'help') {
-    console.log(HELP_TEXT.trimEnd());
-    return 0;
+export function getWindowsShellCommand({
+  env = process.env,
+  platform = process.platform,
+  commandExistsFn = commandExists,
+  fileExistsFn = existsSync
+} = {}) {
+  if (platform !== 'win32') {
+    return null;
   }
 
-  if (parsed.action === 'version') {
-    console.log(getPackageVersion());
-    return 0;
+  if (commandExistsFn('pwsh.exe', { env, platform })) {
+    return 'pwsh.exe';
   }
 
-  if (parsed.action === 'error') {
-    console.error(parsed.message);
-    console.error(`Run "${COMMAND} --help" for usage.`);
-    return 1;
+  if (commandExistsFn('powershell.exe', { env, platform })) {
+    return 'powershell.exe';
   }
 
-  const missing = getMissingRequirements(options);
-  if (missing.length > 0) {
-    console.error(`${COMMAND} cannot start:`);
-    for (const message of missing) {
-      console.error(`- ${message}`);
-    }
-    return 1;
+  const systemPowerShellPath = getSystemWindowsPowerShellPath(env);
+  if (systemPowerShellPath && fileExistsFn(systemPowerShellPath)) {
+    return systemPowerShellPath;
   }
 
-  launchTerminals(options);
-  console.log('Opened Codex CLI, Claude Code, and Cursor CLI in Windows Terminal.');
-  return 0;
+  return null;
 }
 
-export function isEntrypoint(argvPath = process.argv[1], moduleUrl = import.meta.url) {
-  if (!argvPath) {
-    return false;
+export function getMissingRequirements({ platform = process.platform, env = process.env } = {}) {
+  const requirements = HARD_REQUIREMENTS_BY_PLATFORM[platform];
+  if (!requirements) {
+    return ['Windows or macOS is required.'];
   }
 
-  const argvRealPath = realpathSync(resolve(argvPath));
-  const moduleRealPath = realpathSync(fileURLToPath(moduleUrl));
+  const missing = requirements
+    .filter(({ command }) => !commandExists(command, { env, platform }))
+    .map(({ label }) => `${label} was not found in PATH.`);
 
-  return argvRealPath === moduleRealPath;
-}
+  if (platform === 'win32' && !getWindowsShellCommand({ env, platform })) {
+    missing.push('PowerShell (pwsh.exe or powershell.exe) was not found.');
+  }
 
-if (isEntrypoint()) {
-  process.exitCode = main();
+  return missing;
 }
+
+export function getAvailableCliTabs({ env = process.env, platform = process.platform } = {}) {
+  return CLI_COMMANDS.filter(({ command }) => commandExists(command, { env, platform }));
+}
+
+export function getMissingCliLabels({ env = process.env, platform = process.platform } = {}) {
+  return CLI_COMMANDS
+    .filter(({ command }) => !commandExists(command, { env, platform }))
+    .map(({ label }) => label);
+}
+
+export function launchTerminals({ cwd = process.cwd(), env = process.env, platform = process.platform, tabs = CLI_COMMANDS } = {}) {
+  const executable = platform === 'win32' ? 'wt.exe' : 'osascript';
+  const shellCommand = platform === 'win32' ? getWindowsShellCommand({ env, platform }) : undefined;
+  if (platform === 'win32' && !shellCommand) {
+    throw new Error('PowerShell (pwsh.exe or powershell.exe) was not found.');
+  }
+
+  const args = platform === 'win32'
+    ? buildWtArgs({ cwd, tabs, shellCommand })
+    : buildMacTerminalArgs({ cwd, tabs });
+
+  const child = spawn(executable, args, {
+    cwd,
+    env,
+    detached: true,
+    stdio: 'ignore',
+    windowsHide: false
+  });
+
+  child.unref();
+}
+
+export function main(args = process.argv.slice(2), options = {}) {
+  const parsed = parseArgs(args);
+
+  if (parsed.action === 'help') {
+    console.log(HELP_TEXT.trimEnd());
+    return 0;
+  }
+
+  if (parsed.action === 'version') {
+    console.log(getPackageVersion());
+    return 0;
+  }
+
+  if (parsed.action === 'error') {
+    console.error(parsed.message);
+    console.error(`Run "${COMMAND} --help" for usage.`);
+    return 1;
+  }
+
+  const missing = getMissingRequirements(options);
+  if (missing.length > 0) {
+    console.error(`${COMMAND} cannot start:`);
+    for (const message of missing) {
+      console.error(`- ${message}`);
+    }
+    return 1;
+  }
+
+  const missingClis = getMissingCliLabels(options);
+  for (const label of missingClis) {
+    console.warn(`Warning: ${label} was not found in PATH, skipping.`);
+  }
+
+  const availableTabs = getAvailableCliTabs(options);
+  if (availableTabs.length === 0) {
+    console.error(`${COMMAND} cannot start: no CLI tools found in PATH.`);
+    return 1;
+  }
+
+  launchTerminals({ ...options, tabs: availableTabs });
+  const launched = availableTabs.map(({ title }) => title).join(', ');
+  const terminalName = (options.platform ?? process.platform) === 'win32' ? 'Windows Terminal' : 'Terminal.app';
+  console.log(`Opened ${launched} in ${terminalName}.`);
+  return 0;
+}
+
+export function isEntrypoint(argvPath = process.argv[1], moduleUrl = import.meta.url) {
+  if (!argvPath) {
+    return false;
+  }
+
+  const argvRealPath = realpathSync(resolve(argvPath));
+  const moduleRealPath = realpathSync(fileURLToPath(moduleUrl));
+
+  return argvRealPath === moduleRealPath;
+}
+
+if (isEntrypoint()) {
+  process.exitCode = main();
+}

package/package.json

@@ -1,45 +1,71 @@
-{
+{
   "name": "start-ai-cli",
-  "version": "0.1.0",
-  "description": "Open Codex CLI, Claude Code, and Cursor CLI in Windows Terminal tabs from the current directory.",
+  "version": "0.1.1",
+  "description": "Launch Codex CLI, Claude Code, and Cursor CLI together from one project directory in Windows Terminal or macOS Terminal.",
   "type": "module",
+  "main": "bin/start-ai-cli.js",
+  "exports": "./bin/start-ai-cli.js",
   "bin": {
     "start-ai-cli": "bin/start-ai-cli.js"
   },
-  "scripts": {
-    "test": "node --test",
-    "pack:dry-run": "npm pack --dry-run",
-    "publish:dry-run": "npm publish --dry-run"
-  },
-  "files": [
-    "bin/",
-    "README.md",
-    "LICENSE"
-  ],
+  "scripts": {
+    "test": "node --test",
+    "pack:dry-run": "npm pack --dry-run",
+    "publish:dry-run": "npm publish --dry-run"
+  },
+  "files": [
+    "bin/",
+    "README.md",
+    "LICENSE"
+  ],
   "keywords": [
+    "start-ai-cli",
+    "open-ai-cli",
+    "ai-cli",
+    "ai-agent",
+    "ai-coding",
+    "ai-coding-agent",
+    "coding-agent",
     "codex",
+    "codex-cli",
+    "openai-codex",
     "claude",
+    "claude-code",
+    "claude-code-cli",
     "cursor",
+    "cursor-cli",
+    "cursor-agent",
     "cli",
+    "cli-launcher",
+    "developer-tools",
     "terminal",
-    "windows-terminal"
-  ],
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/guoxiao0521/open-ai-cli.git"
-  },
-  "bugs": {
-    "url": "https://github.com/guoxiao0521/open-ai-cli/issues"
-  },
-  "homepage": "https://github.com/guoxiao0521/open-ai-cli#readme",
-  "os": [
-    "win32"
+    "terminal-tabs",
+    "windows-terminal",
+    "macos",
+    "macos-terminal",
+    "productivity"
   ],
-  "engines": {
-    "node": ">=18"
+  "author": {
+    "name": "guoxiao0521",
+    "url": "https://github.com/guoxiao0521"
   },
-  "publishConfig": {
-    "registry": "https://registry.npmjs.org/"
-  }
-}
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/guoxiao0521/open-ai-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/guoxiao0521/open-ai-cli/issues"
+  },
+  "homepage": "https://github.com/guoxiao0521/open-ai-cli#readme",
+  "os": [
+    "win32",
+    "darwin"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  }
+}