agentxchain 0.8.6 → 0.8.8

package/README.md

@@ -16,12 +16,21 @@ npx agentxchain init
 
 ## Quick start
 
+### Happy path: net-new project
+
 ```bash
-# 1. Create a project (interactive template selection)
-agentxchain init
+npx agentxchain init
+cd my-agentxchain-project   # default with init -y, or your chosen folder name
+agentxchain kickoff
+```
+
+### Happy path: existing project
 
-# 2. Run guided PM-first kickoff wizard
-cd my-project/
+Run these commands from inside your existing project folder:
+
+```bash
+agentxchain doctor
+agentxchain generate
 agentxchain kickoff
 ```
 
@@ -43,9 +52,11 @@ Agents are now required to maintain `TALK.md` as the human-readable handoff log
 | `doctor` | Validate local setup (tools, trigger flow, accessibility checks) |
 | `claim` | Human takes control (agents stop claiming) |
 | `release` | Hand lock back to agents |
-| `stop` | Terminate running Claude Code agent sessions |
-| `watch` | Optional: TTL safety net + status logging |
+| `stop` | Stop watch daemon, end Claude Code sessions; Cursor/VS Code chats close manually |
+| `branch` | Show/set Cursor branch override for launches |
+| `watch` | Referee loop: validates turns, writes next trigger, and force-releases stale locks |
 | `config` | View/edit config, add/remove agents, change rules |
+| `rebind` | Rebuild Cursor workspace/prompt bindings for agents |
 | `update` | Self-update CLI from npm |
 
 ### Full command list
@@ -56,7 +67,9 @@ agentxchain status
 agentxchain start
 agentxchain kickoff
 agentxchain stop
+agentxchain branch
 agentxchain config
+agentxchain rebind
 agentxchain generate
 agentxchain watch
 agentxchain supervise
@@ -94,40 +107,28 @@ agentxchain watch --daemon          # run watch in background
 agentxchain supervise --autonudge   # run watch + AppleScript nudge loop
 agentxchain supervise --autonudge --send   # auto-press Enter after paste
 agentxchain supervise --interval 2  # set auto-nudge poll interval
+agentxchain rebind                  # regenerate agent prompt/workspace bindings
+agentxchain rebind --open           # regenerate and reopen all Cursor agent windows
+agentxchain rebind --agent pm       # regenerate one agent binding only
 agentxchain claim --agent pm        # guarded claim as agent turn owner
 agentxchain release --agent pm      # guarded release as agent turn owner
 agentxchain release --force         # force-release non-human holder lock
+agentxchain config --set "rules.strict_next_owner true"  # TALK-only next owner (no cyclic fallback)
 ```
 
 ## macOS auto-nudge (AppleScript)
 
-If you want the next agent chat to be nudged automatically when turn changes, use the built-in AppleScript helper.
-
-1) Keep watcher running in your project:
+**Recommended:** `agentxchain supervise --autonudge` (starts `watch` + auto-nudge together). Requires macOS, `jq`, and Accessibility for Terminal + Cursor.
 
 ```bash
-agentxchain watch
-# or use the combined command:
 agentxchain supervise --autonudge
+agentxchain supervise --autonudge --send   # paste + Enter
 ```
 
-2) In another terminal (from `cli/`), start auto-nudge:
-
-```bash
-bash scripts/run-autonudge.sh --project "/absolute/path/to/your-project"
-```
-
-By default this is **paste-only** (safe mode): it opens chat and pastes the nudge message, but does not press Enter.
-
-3) Enable auto-send once confirmed:
-
-```bash
-bash scripts/run-autonudge.sh --project "/absolute/path/to/your-project" --send
-```
-
-Stop it anytime:
+**Advanced (debugging):** from a checkout of `cli/`, run the script alone while `watch` is already running:
 
 ```bash
+bash scripts/run-autonudge.sh --project "/absolute/path/to/your-project" [--send]
 bash scripts/stop-autonudge.sh
 ```
 
@@ -146,22 +147,21 @@ Notes:
 2. Each window gets a unique prompt copied to clipboard
 3. Kickoff validates PM signoff and launches remaining agents
 4. Agent prompts are single-turn: claim → work → validate → release → stop
-5. Agents know their rotation order from `agentxchain.json` and only claim when the previous agent released
+5. Agents use the latest `Next owner:` in `TALK.md` to pick who goes next (fallback: config order)
 6. Human can `claim` to pause and `release` to resume anytime
 
 ### VS Code mode
 
 1. `agentxchain init` generates `.github/agents/*.agent.md` (VS Code custom agents) and `.github/hooks/` (lifecycle hooks)
-2. VS Code auto-discovers agents in the Chat dropdown
+2. VS Code discovers custom agents in Chat when using **GitHub Copilot** agents (see Microsoft docs)
 3. The `Stop` hook acts as referee — hands off to next agent automatically
 
-### Turn rotation
+### Turn ownership
 
-Agents follow a round-robin order defined in `agentxchain.json`:
-- PM waits for: lock free + last released by `human`, `null`, or last agent in rotation
-- Dev waits for: lock free + last released by `pm`
-- QA waits for: lock free + last released by `dev`
-- And so on...
+Agent turns are handoff-driven:
+- Each turn appends a `Next owner:` in `TALK.md` with a valid agent id
+- `watch`/`supervise` dispatches the next trigger from that handoff
+- `claim --agent <id>` enforces that expected owner (with guarded fallback)
 
 ## Key features
 
@@ -176,14 +176,12 @@ Agents follow a round-robin order defined in `agentxchain.json`:
 
 ## VS Code extension (optional)
 
-For a richer UI in VS Code:
+The VSIX is not committed to the repo. Build/package from `cli/vscode-extension/` (see that folder’s README or `vsce package`), then:
 
 ```bash
-code --install-extension cli/vscode-extension/agentxchain-0.1.0.vsix
+code --install-extension /path/to/agentxchain-*.vsix
 ```
 
-Adds: status bar (lock holder, turn, phase), sidebar dashboard, command palette integration.
-
 ## Publish updates (maintainers)
 
 ```bash

package/bin/agentxchain.js

@@ -1,9 +1,52 @@
 #!/usr/bin/env node
 
-import { readFileSync } from 'fs';
-import { join, dirname } from 'path';
+import { readFileSync, existsSync } from 'fs';
+import { join, dirname, parse as pathParse, resolve } from 'path';
 import { fileURLToPath } from 'url';
 import { Command } from 'commander';
+
+// Load .env from AgentXchain project root when available, then cwd as fallback.
+(function loadDotenv() {
+  const cwd = process.cwd();
+  const projectRoot = findNearestProjectRoot(cwd);
+  const envPaths = [];
+
+  if (projectRoot) {
+    envPaths.push(join(projectRoot, '.env'));
+  }
+  if (!projectRoot || projectRoot !== cwd) {
+    envPaths.push(join(cwd, '.env'));
+  }
+
+  for (const envPath of envPaths) {
+    if (!existsSync(envPath)) continue;
+    try {
+      const content = readFileSync(envPath, 'utf8');
+      for (const line of content.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#')) continue;
+        const eqIdx = trimmed.indexOf('=');
+        if (eqIdx === -1) continue;
+        const key = trimmed.slice(0, eqIdx).trim();
+        let val = trimmed.slice(eqIdx + 1).trim();
+        if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+          val = val.slice(1, -1);
+        }
+        if (!process.env[key]) process.env[key] = val;
+      }
+    } catch {}
+  }
+})();
+
+function findNearestProjectRoot(startDir) {
+  let dir = resolve(startDir);
+  const { root: fsRoot } = pathParse(dir);
+  while (true) {
+    if (existsSync(join(dir, 'agentxchain.json'))) return dir;
+    if (dir === fsRoot) return null;
+    dir = join(dir, '..');
+  }
+}
 import { initCommand } from '../src/commands/init.js';
 import { statusCommand } from '../src/commands/status.js';
 import { startCommand } from '../src/commands/start.js';
@@ -17,6 +60,8 @@ import { doctorCommand } from '../src/commands/doctor.js';
 import { superviseCommand } from '../src/commands/supervise.js';
 import { validateCommand } from '../src/commands/validate.js';
 import { kickoffCommand } from '../src/commands/kickoff.js';
+import { rebindCommand } from '../src/commands/rebind.js';
+import { branchCommand } from '../src/commands/branch.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
@@ -60,7 +105,7 @@ program
 
 program
   .command('stop')
-  .description('Stop all running agent sessions')
+  .description('Stop watch daemon and Claude Code sessions; close Cursor/VS Code chats manually')
   .action(stopCommand);
 
 program
@@ -72,6 +117,13 @@ program
   .option('-j, --json', 'Output config as JSON')
   .action(configCommand);
 
+program
+  .command('branch [name]')
+  .description('Show or set the Cursor branch used for launches')
+  .option('--use-current', 'Set override to the current local git branch')
+  .option('--unset', 'Remove override and follow the active git branch automatically')
+  .action(branchCommand);
+
 program
   .command('generate')
   .description('Regenerate VS Code agent files (.agent.md, hooks) from agentxchain.json')
@@ -91,6 +143,13 @@ program
   .option('--interval <seconds>', 'Auto-nudge poll interval in seconds', '3')
   .action(superviseCommand);
 
+program
+  .command('rebind')
+  .description('Rebuild Cursor prompt/workspace bindings for agents')
+  .option('--agent <id>', 'Rebind a single agent only')
+  .option('--open', 'Reopen Cursor windows after rebinding')
+  .action(rebindCommand);
+
 program
   .command('claim')
   .description('Claim the lock as a human (take control)')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "0.8.6",
+  "version": "0.8.8",
   "description": "CLI for AgentXchain — multi-agent coordination in your IDE",
   "type": "module",
   "bin": {
@@ -14,6 +14,7 @@
   ],
   "scripts": {
     "dev": "node bin/agentxchain.js",
+    "test": "node --test test/*.test.js",
     "build:macos": "bun build bin/agentxchain.js --compile --target=bun-darwin-arm64 --outfile=dist/agentxchain-macos-arm64",
     "build:linux": "bun build bin/agentxchain.js --compile --target=bun-linux-x64 --outfile=dist/agentxchain-linux-x64",
     "publish:npm": "bash scripts/publish-npm.sh"
@@ -43,6 +44,6 @@
     "ora": "^8.0.0"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=18.17.0 || >=20.5.0"
   }
 }

package/scripts/agentxchain-autonudge.applescript

@@ -1,6 +1,7 @@
 property projectRoot : ""
 property pollSeconds : 3
 property autoSend : false
+property lastFailedDispatch : ""
 
 on run argv
   if (count of argv) < 1 then
@@ -41,8 +42,10 @@ on run argv
           set lastKey to do shell script "test -f " & quoted form of statePath & " && cat " & quoted form of statePath & " || echo ''"
 
           if dispatchKey is not lastKey then
-            my nudgeAgent(agentId, turnNum)
-            do shell script "printf %s " & quoted form of dispatchKey & " > " & quoted form of statePath
+            set nudgedOk to my nudgeAgent(agentId, turnNum, dispatchKey)
+            if nudgedOk then
+              do shell script "printf %s " & quoted form of dispatchKey & " > " & quoted form of statePath
+            end if
           end if
         end if
       end if
@@ -52,35 +55,67 @@ on run argv
   end repeat
 end run
 
-on nudgeAgent(agentId, turnNum)
+on nudgeAgent(agentId, turnNum, dispatchKey)
   set nudgeText to "Hey " & agentId & ", it is your turn now (turn " & turnNum & "). Read lock.json, claim the lock, check state.md + history.jsonl + planning docs, do your work, and release lock."
   set the clipboard to nudgeText
 
+  tell application "System Events"
+    if not (exists process "Cursor") then
+      if lastFailedDispatch is not dispatchKey then
+        do shell script "osascript -e " & quoted form of ("display notification \"Cursor is not running.\" with title \"AgentXchain\"")
+        set lastFailedDispatch to dispatchKey
+      end if
+      return false
+    end if
+  end tell
+
   tell application "Cursor" to activate
-  delay 0.5
+  delay 0.6
+
+  -- Verify Cursor is actually frontmost before sending keystrokes
+  tell application "System Events"
+    set frontApp to name of first application process whose frontmost is true
+    if frontApp is not "Cursor" then
+      if lastFailedDispatch is not dispatchKey then
+        do shell script "osascript -e " & quoted form of ("display notification \"Cursor lost focus, skipping nudge for " & agentId & ".\" with title \"AgentXchain\"")
+        set lastFailedDispatch to dispatchKey
+      end if
+      return false
+    end if
+  end tell
+
   set focusedOk to my focusAgentWindow(agentId)
   if focusedOk is false then
-    do shell script "osascript -e " & quoted form of ("display notification \"Could not identify a unique window for " & agentId & ".\" with title \"AgentXchain\"")
-    return
+    if lastFailedDispatch is not dispatchKey then
+      do shell script "osascript -e " & quoted form of ("display notification \"Could not identify a unique window for " & agentId & ".\" with title \"AgentXchain\"")
+      set lastFailedDispatch to dispatchKey
+    end if
+    return false
   end if
-  delay 0.2
+  delay 0.3
 
+  -- Re-verify focus before keystrokes
   tell application "System Events"
-    if not (exists process "Cursor") then return
+    set frontApp to name of first application process whose frontmost is true
+    if frontApp is not "Cursor" then
+      return false
+    end if
 
     tell process "Cursor"
       set frontmost to true
       keystroke "l" using {command down}
-      delay 0.2
+      delay 0.3
       keystroke "v" using {command down}
       if autoSend then
-        delay 0.15
+        delay 0.2
         key code 36
       end if
     end tell
   end tell
 
+  set lastFailedDispatch to ""
   do shell script "osascript -e " & quoted form of ("display notification \"Nudged " & agentId & " for turn " & turnNum & "\" with title \"AgentXchain\"")
+  return true
 end nudgeAgent
 
 on focusAgentWindow(agentId)
@@ -117,6 +152,10 @@ end focusAgentWindow
 
 on isStrongWindowMatch(windowName, agentId)
   set tokenA to ".agentxchain-workspaces/" & agentId
+  set tokenB to ".agentxchain-workspaces\\" & agentId
+  set tokenC to agentId & ".code-workspace"
   if windowName contains tokenA then return true
+  if windowName contains tokenB then return true
+  if windowName contains tokenC then return true
   return false
 end isStrongWindowMatch

package/scripts/run-autonudge.sh

@@ -104,7 +104,7 @@ echo "Mode:      $( [[ "${AUTO_SEND}" == "true" ]] && echo "auto-send" || echo "
 echo "Interval:  ${INTERVAL_SECONDS}s"
 echo ""
 echo "Requirements:"
-echo "- Keep 'agentxchain watch' running in another terminal."
+echo "- Watch must be running (e.g. 'agentxchain supervise --autonudge' starts it in the same supervisor, or run 'agentxchain watch' in another terminal)."
 echo "- Grant Accessibility permission to Terminal and Cursor."
 echo ""
 

package/src/adapters/claude-code.js

@@ -1,8 +1,9 @@
 import { spawn } from 'child_process';
 import chalk from 'chalk';
 import { generateSeedPrompt } from '../lib/seed-prompt.js';
-import { writeFileSync } from 'fs';
 import { join } from 'path';
+import { safeWriteJson } from '../lib/safe-write.js';
+import { filterAgents } from '../lib/filter-agents.js';
 
 export async function launchClaudeCodeAgents(config, root, opts) {
   const agents = filterAgents(config, opts.agent);
@@ -28,22 +29,14 @@ export async function launchClaudeCodeAgents(config, root, opts) {
   }
 
   if (launched.length > 0) {
-    const sessionFile = JSON.stringify({ launched, started_at: new Date().toISOString(), ide: 'claude-code' }, null, 2);
-    writeFileSync(join(root, '.agentxchain-session.json'), sessionFile + '\n');
+    safeWriteJson(join(root, '.agentxchain-session.json'), {
+      launched,
+      started_at: new Date().toISOString(),
+      ide: 'claude-code'
+    });
     console.log('');
     console.log(chalk.dim(`  Session saved to .agentxchain-session.json`));
   }
 
   return launched;
 }
-
-function filterAgents(config, specificId) {
-  if (specificId) {
-    if (!config.agents[specificId]) {
-      console.log(chalk.red(`  Agent "${specificId}" not found in agentxchain.json`));
-      process.exit(1);
-    }
-    return { [specificId]: config.agents[specificId] };
-  }
-  return config.agents;
-}

package/src/adapters/cursor-local.js

@@ -1,9 +1,10 @@
 import { execSync } from 'child_process';
-import { writeFileSync, mkdirSync, existsSync, symlinkSync, lstatSync, unlinkSync } from 'fs';
+import { writeFileSync, mkdirSync } from 'fs';
 import { join } from 'path';
 import chalk from 'chalk';
 import inquirer from 'inquirer';
 import { generatePollingPrompt } from '../lib/seed-prompt-polling.js';
+import { filterAgents } from '../lib/filter-agents.js';
 
 export async function launchCursorLocal(config, root, opts) {
   const agents = filterAgents(config, opts.agent);
@@ -29,7 +30,7 @@ export async function launchCursorLocal(config, root, opts) {
     writeFileSync(join(promptDir, `${id}.prompt.md`), prompt);
   }
 
-  // Create per-agent symlinked workspace folders so Cursor opens separate windows
+  // Create per-agent workspace files so each Cursor window has a unique identity
   const workspacesDir = join(root, '.agentxchain-workspaces');
   mkdirSync(workspacesDir, { recursive: true });
 
@@ -39,28 +40,33 @@ export async function launchCursorLocal(config, root, opts) {
       ? generateKickoffPrompt(id, agent, config, root)
       : generatePollingPrompt(id, agent, config, root);
 
-    // Create symlink: .agentxchain-workspaces/<id> -> project root
-    const agentWorkspace = join(workspacesDir, id);
-    try {
-      if (existsSync(agentWorkspace)) {
-        const stat = lstatSync(agentWorkspace);
-        if (stat.isSymbolicLink()) unlinkSync(agentWorkspace);
-      }
-      if (!existsSync(agentWorkspace)) {
-        symlinkSync(root, agentWorkspace, 'dir');
-      }
-    } catch {}
+    // Create workspace file: .agentxchain-workspaces/<id>.code-workspace
+    const agentWorkspace = join(workspacesDir, `${id}.code-workspace`);
+    const workspaceJson = {
+      folders: [{ path: root }],
+      settings: { 'agentxchain.agentId': id }
+    };
+    writeFileSync(agentWorkspace, JSON.stringify(workspaceJson, null, 2) + '\n');
 
     console.log(chalk.cyan(`  ─── Agent ${i + 1}/${total}: ${chalk.bold(id)} — ${agent.name} ───`));
     console.log('');
 
-    copyToClipboard(prompt);
-    console.log(chalk.green(`  ✓ Prompt copied to clipboard.`));
+    const copied = copyToClipboard(prompt);
+    if (copied) {
+      console.log(chalk.green('  ✓ Prompt copied to clipboard.'));
+    } else {
+      console.log(chalk.yellow('  ! Clipboard copy failed. Use the saved prompt file manually.'));
+    }
     console.log(chalk.dim(`    Saved to: .agentxchain-prompts/${id}.prompt.md`));
 
     // Open a separate Cursor window using the symlinked path
-    openCursorWindow(agentWorkspace);
-    console.log(chalk.dim(`    Cursor window opened for ${id}.`));
+    const opened = openCursorWindow(agentWorkspace);
+    if (opened) {
+      console.log(chalk.dim(`    Cursor window opened for ${id}.`));
+    } else {
+      console.log(chalk.yellow(`    Could not open Cursor window automatically for ${id}.`));
+      console.log(chalk.dim(`    Open manually: cursor --new-window "${agentWorkspace}"`));
+    }
 
     console.log('');
     console.log(`  ${chalk.bold('In the new Cursor window:')}`);
@@ -112,17 +118,6 @@ export async function launchCursorLocal(config, root, opts) {
   console.log('');
 }
 
-function filterAgents(config, specificId) {
-  if (specificId) {
-    if (!config.agents[specificId]) {
-      console.log(chalk.red(`  Agent "${specificId}" not found in agentxchain.json`));
-      process.exit(1);
-    }
-    return { [specificId]: config.agents[specificId] };
-  }
-  return config.agents;
-}
-
 function copyToClipboard(text) {
   try {
     if (process.platform === 'darwin') {
@@ -141,10 +136,12 @@ function openCursorWindow(folderPath) {
   try {
     if (process.platform === 'darwin') {
       execSync(`open -na "Cursor" --args "${folderPath}"`, { stdio: 'ignore' });
-      return;
+      return true;
     }
     execSync(`cursor --new-window "${folderPath}"`, { stdio: 'ignore' });
+    return true;
   } catch {}
+  return false;
 }
 
 function isPmLike(agentId, agentDef) {

package/src/commands/branch.js

@@ -1,7 +1,7 @@
-import { writeFileSync } from 'fs';
 import { join } from 'path';
 import chalk from 'chalk';
 import { loadConfig, CONFIG_FILE } from '../lib/config.js';
+import { safeWriteJson } from '../lib/safe-write.js';
 import { getCurrentBranch } from '../lib/repo.js';
 
 export async function branchCommand(name, opts) {
@@ -94,5 +94,5 @@ function setBranchOverride(config, configPath, branch) {
 }
 
 function saveConfig(configPath, config) {
-  writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+  safeWriteJson(configPath, config);
 }