agentxchain 0.4.0 → 0.4.1

package/README.md

@@ -19,35 +19,63 @@ npx agentxchain init
 ```bash
 agentxchain init                      # create a project (template selection)
 cd my-project/
-export CURSOR_API_KEY=your_key        # from cursor.com/settings
+echo "CURSOR_API_KEY=your_key" >> .env # from cursor.com/settings -> Cloud Agents
 agentxchain start --ide cursor        # launch agents
 agentxchain watch                     # coordinate turns automatically
 ```
 
+> `CURSOR_API_KEY` is required for Cursor commands (`start/watch/stop/claim/release` when using Cursor sessions).
+
 ## Commands
 
 | Command | What it does |
 |---------|-------------|
 | `init` | Create project folder with agents, protocol files, and templates |
-| `start` | Launch agents in Cursor, Claude Code, or VS Code |
+| `start` | Launch agents in Cursor, Claude Code, or VS Code (`CURSOR_API_KEY` required for Cursor) |
 | `watch` | The referee — coordinates turns, enforces TTL, wakes agents |
 | `status` | Show lock, phase, agents, Cursor session info |
 | `claim` | Human takes control (pauses Cursor agents) |
 | `release` | Hand lock back to agents |
 | `stop` | Terminate all running agents |
+| `branch` | Show/set Cursor branch override (`cursor.ref`) |
 | `config` | View/edit config, add/remove agents, change rules |
 | `update` | Self-update CLI from npm |
 
+### Branch selection
+
+By default, Cursor launches use your current local git branch. You can override this when needed.
+
+```bash
+agentxchain branch                  # show current/effective branch
+agentxchain branch develop          # pin to a specific branch
+agentxchain branch --use-current    # pin to whatever branch you're on now
+agentxchain branch --unset          # remove pin; follow active git branch
+```
+
 ## Key features
 
 - **Claim-based coordination** — no fixed turn order; agents self-organize
 - **User-defined teams** — any number of agents, any roles
 - **Cursor Cloud Agents** — launch and manage agents via API
+- **Branch-safe launching** — defaults to active git branch; optional `branch` override
+- **Project `.env` loading** — CLI auto-reads `CURSOR_API_KEY` from project root `.env`
 - **Lock TTL** — stale locks auto-released after timeout
 - **Verify command** — agents must pass tests before releasing
 - **Human-in-the-loop** — claim/release to intervene anytime
 - **Team templates** — SaaS MVP, Landing Page, Bug Squad, API Builder, Refactor Team
 
+## Publish updates (maintainers)
+
+```bash
+cd cli
+bash scripts/publish-npm.sh              # patch bump + publish
+bash scripts/publish-npm.sh minor        # minor bump + publish
+bash scripts/publish-npm.sh 0.5.0        # explicit version + publish
+bash scripts/publish-npm.sh patch --dry-run
+```
+
+If `NPM_TOKEN` exists in `cli/.env`, the script uses it automatically.
+
 ## Links
 
 - [agentxchain.dev](https://agentxchain.dev)

package/bin/agentxchain.js

@@ -9,13 +9,14 @@ import { configCommand } from '../src/commands/config.js';
 import { updateCommand } from '../src/commands/update.js';
 import { watchCommand } from '../src/commands/watch.js';
 import { claimCommand, releaseCommand } from '../src/commands/claim.js';
+import { branchCommand } from '../src/commands/branch.js';
 
 const program = new Command();
 
 program
   .name('agentxchain')
   .description('Multi-agent coordination in your IDE')
-  .version('0.1.1');
+  .version('0.4.0');
 
 program
   .command('init')
@@ -51,6 +52,13 @@ program
   .option('-j, --json', 'Output config as JSON')
   .action(configCommand);
 
+program
+  .command('branch [name]')
+  .description('Show or set the Cursor branch used for agent launches')
+  .option('--use-current', 'Set override to the current local git branch')
+  .option('--unset', 'Remove override and follow active git branch automatically')
+  .action(branchCommand);
+
 program
   .command('watch')
   .description('Watch lock.json and coordinate agent turns (the referee)')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "CLI for AgentXchain — multi-agent coordination in your IDE",
   "type": "module",
   "bin": {
@@ -14,7 +14,8 @@
   "scripts": {
     "dev": "node bin/agentxchain.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"
+    "build:linux": "bun build bin/agentxchain.js --compile --target=bun-linux-x64 --outfile=dist/agentxchain-linux-x64",
+    "publish:npm": "bash scripts/publish-npm.sh"
   },
   "keywords": [
     "ai",

package/src/adapters/cursor.js

@@ -2,7 +2,8 @@ import { writeFileSync, readFileSync, existsSync } from 'fs';
 import { join } from 'path';
 import chalk from 'chalk';
 import { generateSeedPrompt } from '../lib/seed-prompt.js';
-import { getRepoUrl } from '../lib/repo.js';
+import { getRepoUrl, getCurrentBranch } from '../lib/repo.js';
+import { getCursorApiKey, printCursorApiKeyRequired } from '../lib/cursor-api-key.js';
 
 const API_BASE = 'https://api.cursor.com/v0';
 
@@ -16,11 +17,11 @@ function authHeaders(apiKey) {
 // --- Public API ---
 
 export async function launchCursorAgents(config, root, opts) {
-  const apiKey = process.env.CURSOR_API_KEY;
+  const apiKey = getCursorApiKey(root);
 
   if (!apiKey) {
-    printApiKeyHelp();
-    return fallbackPromptOutput(config, opts);
+    printCursorApiKeyRequired('`agentxchain start --ide cursor`');
+    return [];
   }
 
   const repoUrl = await getRepoUrl(root);
@@ -32,9 +33,11 @@ export async function launchCursorAgents(config, root, opts) {
   }
 
   const model = config.cursor?.model || 'default';
-  const ref = config.cursor?.ref || 'main';
+  const ref = config.cursor?.ref || getCurrentBranch(root) || 'main';
+  console.log(chalk.dim(`  Cursor source: ${repoUrl} @ ${ref}`));
   const agents = filterAgents(config, opts.agent);
   const launched = [];
+  let branchErrorCount = 0;
 
   for (const [id, agent] of Object.entries(agents)) {
     const prompt = generateSeedPrompt(id, agent, config);
@@ -56,6 +59,9 @@ export async function launchCursorAgents(config, root, opts) {
       if (!res.ok) {
         const errBody = await res.text();
         console.log(chalk.red(`  ✗ ${id}: ${res.status} ${errBody}`));
+        if (errBody.includes('Failed to verify existence of branch')) {
+          branchErrorCount += 1;
+        }
         continue;
       }
 
@@ -76,7 +82,16 @@ export async function launchCursorAgents(config, root, opts) {
   }
 
   if (launched.length > 0) {
-    saveSession(root, launched, repoUrl);
+    saveSession(root, launched, repoUrl, ref);
+  }
+
+  if (launched.length === 0 && branchErrorCount > 0) {
+    console.log('');
+    console.log(chalk.yellow('  Launch failed because the branch ref is invalid for this repository.'));
+    console.log(chalk.dim('  Fix by setting the branch explicitly in agentxchain.json:'));
+    console.log(chalk.bold('  "cursor": { "ref": "your-default-branch" }'));
+    console.log(chalk.dim('  Or switch to the target branch locally, then re-run start.'));
+    console.log('');
   }
 
   return launched;
@@ -137,12 +152,13 @@ export function loadSession(root) {
 
 // --- Internal ---
 
-function saveSession(root, launched, repoUrl) {
+function saveSession(root, launched, repoUrl, ref) {
   const session = {
     launched,
     started_at: new Date().toISOString(),
     ide: 'cursor',
-    repo: repoUrl
+    repo: repoUrl,
+    ref
   };
   const sessionPath = join(root, '.agentxchain-session.json');
   writeFileSync(sessionPath, JSON.stringify(session, null, 2) + '\n');
@@ -160,29 +176,5 @@ function filterAgents(config, specificId) {
   return config.agents;
 }
 
-function fallbackPromptOutput(config, opts) {
-  const agents = filterAgents(config, opts.agent);
-  console.log(chalk.bold('  No API key. Printing seed prompts for manual use:'));
-  console.log('');
-  for (const [id, agent] of Object.entries(agents)) {
-    const prompt = generateSeedPrompt(id, agent, config);
-    console.log(chalk.dim('  ' + '─'.repeat(50)));
-    console.log(chalk.cyan(`  Agent: ${chalk.bold(id)} (${agent.name})`));
-    console.log(chalk.dim('  ' + '─'.repeat(50)));
-    console.log('');
-    console.log(prompt);
-    console.log('');
-  }
-  return [];
-}
-
-function printApiKeyHelp() {
-  console.log('');
-  console.log(chalk.yellow('  CURSOR_API_KEY not found.'));
-  console.log('');
-  console.log(`  1. Go to ${chalk.cyan('cursor.com/settings')} → Cloud Agents`);
-  console.log('  2. Create an API key');
-  console.log(`  3. Add to .env: ${chalk.bold('CURSOR_API_KEY=your_key')}`);
-  console.log(`  4. Run: ${chalk.bold('source .env && agentxchain start')}`);
-  console.log('');
-}
+// No prompt fallback here by design.
+// Cursor mode is strict: an API key is required.

package/src/commands/branch.js

@@ -0,0 +1,98 @@
+import { writeFileSync } from 'fs';
+import { join } from 'path';
+import chalk from 'chalk';
+import { loadConfig, CONFIG_FILE } from '../lib/config.js';
+import { getCurrentBranch } from '../lib/repo.js';
+
+export async function branchCommand(name, opts) {
+  const result = loadConfig();
+  if (!result) {
+    console.log(chalk.red('  No agentxchain.json found. Run `agentxchain init` first.'));
+    process.exit(1);
+  }
+
+  const { root, config } = result;
+  const configPath = join(root, CONFIG_FILE);
+  const currentGitBranch = getCurrentBranch(root) || 'main';
+  const hasOverride = !!config.cursor?.ref;
+  const overrideBranch = hasOverride ? config.cursor.ref : null;
+
+  if (opts.unset && (name || opts.useCurrent)) {
+    console.log(chalk.red('  Use either --unset OR a branch value, not both.'));
+    process.exit(1);
+  }
+
+  if (name && opts.useCurrent) {
+    console.log(chalk.red('  Use either --use-current OR a branch value, not both.'));
+    process.exit(1);
+  }
+
+  if (opts.unset) {
+    if (config.cursor?.ref) {
+      delete config.cursor.ref;
+      if (config.cursor && Object.keys(config.cursor).length === 0) delete config.cursor;
+      saveConfig(configPath, config);
+    }
+
+    console.log('');
+    console.log(chalk.green('  ✓ Cleared branch override.'));
+    console.log(chalk.dim(`  Effective branch now follows git: ${currentGitBranch}`));
+    console.log('');
+    return;
+  }
+
+  if (opts.useCurrent) {
+    setBranchOverride(config, configPath, currentGitBranch);
+    console.log('');
+    console.log(chalk.green(`  ✓ Set Cursor branch override to current git branch: ${chalk.bold(currentGitBranch)}`));
+    console.log('');
+    return;
+  }
+
+  if (name) {
+    const branch = String(name).trim();
+    if (!branch) {
+      console.log(chalk.red('  Branch cannot be empty.'));
+      process.exit(1);
+    }
+    if (!/^[A-Za-z0-9._/-]+$/.test(branch)) {
+      console.log(chalk.red('  Invalid branch name. Use letters, numbers, ., _, -, /.'));
+      process.exit(1);
+    }
+
+    setBranchOverride(config, configPath, branch);
+    console.log('');
+    console.log(chalk.green(`  ✓ Set Cursor branch override: ${chalk.bold(branch)}`));
+    if (branch !== currentGitBranch) {
+      console.log(chalk.dim(`    (current git branch is ${currentGitBranch})`));
+    }
+    console.log('');
+    return;
+  }
+
+  const effective = overrideBranch || currentGitBranch;
+  console.log('');
+  console.log(chalk.bold('  AgentXchain Branch'));
+  console.log(chalk.dim('  ' + '─'.repeat(36)));
+  console.log('');
+  console.log(`  ${chalk.dim('Current git branch:')} ${currentGitBranch}`);
+  console.log(`  ${chalk.dim('Cursor override:')}    ${overrideBranch || chalk.dim('none')}`);
+  console.log(`  ${chalk.dim('Effective branch:')}   ${chalk.bold(effective)}`);
+  console.log('');
+  console.log(chalk.dim('  Commands:'));
+  console.log(`    ${chalk.bold('agentxchain branch')}               Show effective branch`);
+  console.log(`    ${chalk.bold('agentxchain branch <name>')}        Set branch override`);
+  console.log(`    ${chalk.bold('agentxchain branch --use-current')} Set override to current git branch`);
+  console.log(`    ${chalk.bold('agentxchain branch --unset')}       Follow git branch automatically`);
+  console.log('');
+}
+
+function setBranchOverride(config, configPath, branch) {
+  if (!config.cursor) config.cursor = {};
+  config.cursor.ref = branch;
+  saveConfig(configPath, config);
+}
+
+function saveConfig(configPath, config) {
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+}

package/src/commands/claim.js

@@ -3,6 +3,7 @@ import { join } from 'path';
 import chalk from 'chalk';
 import { loadConfig, loadLock, LOCK_FILE } from '../lib/config.js';
 import { stopAgent, sendFollowup, loadSession } from '../adapters/cursor.js';
+import { getCursorApiKey, printCursorApiKeyRequired } from '../lib/cursor-api-key.js';
 
 export async function claimCommand(opts) {
   const result = loadConfig();
@@ -12,9 +13,17 @@ export async function claimCommand(opts) {
   const lock = loadLock(root);
   if (!lock) { console.log(chalk.red('  lock.json not found.')); process.exit(1); }
 
-  const apiKey = process.env.CURSOR_API_KEY;
+  const apiKey = getCursorApiKey(root);
   const session = loadSession(root);
-  const hasCursor = session?.ide === 'cursor' && apiKey;
+  const hasCursorSession = session?.ide === 'cursor' && session?.launched?.length > 0;
+  const hasCursor = hasCursorSession && apiKey;
+
+  if (hasCursorSession && !apiKey) {
+    printCursorApiKeyRequired('`agentxchain claim` with Cursor agents');
+    console.log(chalk.dim('  Claim aborted so agents are not left running unexpectedly.'));
+    console.log('');
+    process.exit(1);
+  }
 
   if (lock.holder === 'human') {
     console.log('');
@@ -90,8 +99,17 @@ export async function releaseCommand() {
 
   // If releasing from human and Cursor session exists, wake the next agent
   if (who === 'human') {
-    const apiKey = process.env.CURSOR_API_KEY;
+    const apiKey = getCursorApiKey(root);
     const session = loadSession(root);
+    const hasCursorSession = session?.ide === 'cursor' && session?.launched?.length > 0;
+
+    if (hasCursorSession && !apiKey) {
+      printCursorApiKeyRequired('`agentxchain release` with Cursor agents');
+      console.log(chalk.dim('  Lock released, but wake-up followup was skipped due to missing key.'));
+      console.log(chalk.dim('  Start `agentxchain watch` after setting the key.'));
+      console.log('');
+      return;
+    }
 
     if (session?.ide === 'cursor' && apiKey) {
       const agentIds = Object.keys(config.agents);

package/src/commands/init.js

@@ -205,6 +205,25 @@ export async function initCommand(opts) {
   writeFileSync(join(dir, 'history.jsonl'), '');
   writeFileSync(join(dir, 'log.md'), `# ${project} — Agent Log\n\n## COMPRESSED CONTEXT\n\n(No compressed context yet.)\n\n## MESSAGE LOG\n\n(Agents append messages below this line.)\n`);
   writeFileSync(join(dir, 'HUMAN_TASKS.md'), '# Human Tasks\n\n(Agents append tasks here when they need human action.)\n');
+  writeFileSync(join(dir, '.env.example'), 'CURSOR_API_KEY=\n');
+  if (!existsSync(join(dir, '.env'))) {
+    writeFileSync(
+      join(dir, '.env'),
+      '# Required for Cursor commands: start/watch/stop/claim/release\nCURSOR_API_KEY=\n'
+    );
+  }
+  const gitignorePath = join(dir, '.gitignore');
+  const requiredIgnores = ['.env', '.agentxchain-session.json', '.agentxchain-trigger.json'];
+  if (!existsSync(gitignorePath)) {
+    writeFileSync(gitignorePath, requiredIgnores.join('\n') + '\n');
+  } else {
+    const existingIgnore = readFileSync(gitignorePath, 'utf8');
+    const missing = requiredIgnores.filter(entry => !existingIgnore.split(/\r?\n/).includes(entry));
+    if (missing.length > 0) {
+      const prefix = existingIgnore.endsWith('\n') ? '' : '\n';
+      writeFileSync(gitignorePath, existingIgnore + prefix + missing.join('\n') + '\n');
+    }
+  }
 
   // .planning/ structure
   mkdirSync(join(dir, '.planning', 'research'), { recursive: true });
@@ -245,7 +264,8 @@ export async function initCommand(opts) {
   console.log('');
   console.log(`  ${chalk.cyan('Next:')}`);
   console.log(`    ${chalk.bold(`cd ${folderName}`)}`);
+  console.log(`    ${chalk.bold('edit .env')}            ${chalk.dim('# set CURSOR_API_KEY (required for Cursor mode)')}`);
+  console.log(`    ${chalk.bold('agentxchain start')}    ${chalk.dim('# launch agents in Cursor')}`);
   console.log(`    ${chalk.bold('agentxchain watch')}    ${chalk.dim('# start the referee')}`);
-  console.log(`    ${chalk.bold('agentxchain start')}    ${chalk.dim('# launch agents in your IDE')}`);
   console.log('');
 }

package/src/commands/start.js

@@ -1,7 +1,7 @@
 import chalk from 'chalk';
-import ora from 'ora';
 import { loadConfig } from '../lib/config.js';
 import { generateSeedPrompt } from '../lib/seed-prompt.js';
+import { getCursorApiKey, printCursorApiKeyRequired } from '../lib/cursor-api-key.js';
 
 export async function startCommand(opts) {
   const result = loadConfig();
@@ -33,6 +33,11 @@ export async function startCommand(opts) {
 
   switch (ide) {
     case 'cursor': {
+      const apiKey = getCursorApiKey(root);
+      if (!apiKey) {
+        printCursorApiKeyRequired('`agentxchain start --ide cursor`');
+        process.exit(1);
+      }
       const { launchCursorAgents } = await import('../adapters/cursor.js');
       await launchCursorAgents(config, root, opts);
       break;

package/src/commands/status.js

@@ -1,6 +1,7 @@
 import chalk from 'chalk';
 import { loadConfig, loadLock, loadState } from '../lib/config.js';
 import { getAgentStatus, loadSession } from '../adapters/cursor.js';
+import { getCursorApiKey } from '../lib/cursor-api-key.js';
 
 export async function statusCommand(opts) {
   const result = loadConfig();
@@ -52,13 +53,16 @@ export async function statusCommand(opts) {
 
   // Cursor session info
   const session = loadSession(root);
-  const apiKey = process.env.CURSOR_API_KEY;
+  const apiKey = getCursorApiKey(root);
   const hasCursor = session?.ide === 'cursor' && session?.launched?.length > 0;
 
   if (hasCursor) {
     console.log(`  ${chalk.dim('Cursor:')}   ${chalk.cyan('Active session')} (${session.launched.length} agents)`);
     console.log(`  ${chalk.dim('Started:')}  ${session.started_at}`);
     if (session.repo) console.log(`  ${chalk.dim('Repo:')}     ${session.repo}`);
+    if (!apiKey) {
+      console.log(`  ${chalk.dim('API key:')}  ${chalk.red('Missing')} (set CURSOR_API_KEY in .env for live statuses)`);
+    }
     console.log('');
   }
 

package/src/commands/stop.js

@@ -2,7 +2,8 @@ import { readFileSync, existsSync, unlinkSync } from 'fs';
 import { join } from 'path';
 import chalk from 'chalk';
 import { loadConfig } from '../lib/config.js';
-import { deleteAgent, stopAgent, loadSession } from '../adapters/cursor.js';
+import { deleteAgent, loadSession } from '../adapters/cursor.js';
+import { getCursorApiKey, printCursorApiKeyRequired } from '../lib/cursor-api-key.js';
 
 const SESSION_FILE = '.agentxchain-session.json';
 
@@ -24,22 +25,24 @@ export async function stopCommand() {
   console.log('');
 
   if (session.ide === 'cursor') {
-    const apiKey = process.env.CURSOR_API_KEY;
+    const apiKey = getCursorApiKey(root);
     if (!apiKey) {
-      console.log(chalk.yellow('  CURSOR_API_KEY not set. Cannot stop agents via API.'));
-      console.log(chalk.dim('  Stop them manually at cursor.com/agents'));
-    } else {
-      for (const agent of session.launched) {
-        try {
-          const deleted = await deleteAgent(apiKey, agent.cloudId);
-          if (deleted) {
-            console.log(chalk.green(`  ✓ Deleted ${chalk.bold(agent.id)} (${agent.cloudId})`));
-          } else {
-            console.log(chalk.yellow(`  ⚠ Could not delete ${agent.id} — may already be gone`));
-          }
-        } catch (err) {
-          console.log(chalk.red(`  ✗ ${agent.id}: ${err.message}`));
+      printCursorApiKeyRequired('`agentxchain stop` for Cursor agents');
+      console.log(chalk.dim('  Session file was kept so you can retry after setting the key.'));
+      console.log('');
+      return;
+    }
+
+    for (const agent of session.launched) {
+      try {
+        const deleted = await deleteAgent(apiKey, agent.cloudId);
+        if (deleted) {
+          console.log(chalk.green(`  ✓ Deleted ${chalk.bold(agent.id)} (${agent.cloudId})`));
+        } else {
+          console.log(chalk.yellow(`  ⚠ Could not delete ${agent.id} — may already be gone`));
         }
+      } catch (err) {
+        console.log(chalk.red(`  ✗ ${agent.id}: ${err.message}`));
       }
     }
   } else if (session.ide === 'claude-code') {

package/src/commands/watch.js

@@ -4,6 +4,7 @@ import chalk from 'chalk';
 import { loadConfig, loadLock, LOCK_FILE } from '../lib/config.js';
 import { notifyHuman as sendNotification } from '../lib/notify.js';
 import { sendFollowup, getAgentStatus, stopAgent, loadSession } from '../adapters/cursor.js';
+import { getCursorApiKey, printCursorApiKeyRequired } from '../lib/cursor-api-key.js';
 
 export async function watchCommand(opts) {
   const result = loadConfig();
@@ -16,10 +17,15 @@ export async function watchCommand(opts) {
   const interval = config.rules?.watch_interval_ms || 5000;
   const ttlMinutes = config.rules?.ttl_minutes || 10;
   const agentIds = Object.keys(config.agents);
-  const apiKey = process.env.CURSOR_API_KEY;
+  const apiKey = getCursorApiKey(root);
   const session = loadSession(root);
   const hasCursorSession = session?.ide === 'cursor' && session?.launched?.length > 0;
 
+  if (hasCursorSession && !apiKey) {
+    printCursorApiKeyRequired('`agentxchain watch` with a Cursor session');
+    process.exit(1);
+  }
+
   console.log('');
   console.log(chalk.bold('  AgentXchain Watch'));
   console.log(chalk.dim(`  Project: ${config.project}`));

package/src/lib/cursor-api-key.js

@@ -0,0 +1,61 @@
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import chalk from 'chalk';
+
+function parseEnvFile(raw) {
+  const out = {};
+  const lines = raw.split(/\r?\n/);
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    const eq = trimmed.indexOf('=');
+    if (eq === -1) continue;
+
+    const key = trimmed.slice(0, eq).trim();
+    let value = trimmed.slice(eq + 1).trim();
+
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+
+    if (key) out[key] = value;
+  }
+
+  return out;
+}
+
+export function hydrateEnvFromProject(root) {
+  if (!root) return;
+
+  const envPath = join(root, '.env');
+  if (!existsSync(envPath)) return;
+
+  try {
+    const parsed = parseEnvFile(readFileSync(envPath, 'utf8'));
+    for (const [k, v] of Object.entries(parsed)) {
+      if (!process.env[k] && v !== undefined) process.env[k] = v;
+    }
+  } catch {
+    // Non-fatal: commands still work with shell env vars.
+  }
+}
+
+export function getCursorApiKey(root) {
+  hydrateEnvFromProject(root);
+  const key = process.env.CURSOR_API_KEY?.trim();
+  return key || null;
+}
+
+export function printCursorApiKeyRequired(commandName = 'this command') {
+  console.log('');
+  console.log(chalk.red(`  CURSOR_API_KEY is required for ${commandName}.`));
+  console.log(chalk.dim('  Set it once in your project root .env file:'));
+  console.log(`  ${chalk.bold('CURSOR_API_KEY=your_key')}`);
+  console.log(chalk.dim('  You can get a key from: cursor.com/settings -> Cloud Agents'));
+  console.log('');
+}

package/src/lib/repo.js

@@ -30,8 +30,16 @@ export async function getRepoUrl(root) {
 
 export function getCurrentBranch(root) {
   try {
-    return execSync('git rev-parse --abbrev-ref HEAD', { cwd: root, encoding: 'utf8' }).trim();
+    const current = execSync('git rev-parse --abbrev-ref HEAD', { cwd: root, encoding: 'utf8' }).trim();
+    if (current && current !== 'HEAD') return current;
+  } catch {}
+
+  try {
+    const remoteHead = execSync('git symbolic-ref --short refs/remotes/origin/HEAD', { cwd: root, encoding: 'utf8' }).trim();
+    if (remoteHead.includes('/')) return remoteHead.split('/').pop();
   } catch {
     return 'main';
   }
+
+  return 'main';
 }