overlord-cli 4.1.0 → 4.5.0

package/bin/_cli/setup.mjs

@@ -24,6 +24,8 @@ const PACKAGE_PLUGIN_DIR = path.resolve(__dirname, '..', '..', 'plugins', 'overl
 const REPO_PLUGIN_DIR = path.resolve(__dirname, '..', '..', '..', '..', 'plugins', 'overlord');
 const PACKAGE_CLAUDE_PLUGIN_DIR = path.resolve(__dirname, '..', '..', 'plugins', 'claude');
 const REPO_CLAUDE_PLUGIN_DIR = path.resolve(__dirname, '..', '..', '..', '..', 'plugins', 'claude');
+const PACKAGE_CURSOR_PLUGIN_DIR = path.resolve(__dirname, '..', '..', 'plugins', 'cursor');
+const REPO_CURSOR_PLUGIN_DIR = path.resolve(__dirname, '..', '..', '..', '..', 'plugins', 'cursor');
 const CODEX_TARGET_PLUGIN_DIR = path.join(os.homedir(), '.codex', 'plugins', 'overlord');
 const CODEX_TARGET_PLUGIN_MANIFEST = path.join(
   CODEX_TARGET_PLUGIN_DIR,
@@ -479,9 +481,7 @@ function currentContentHashForAgent(agent) {
     return claudeContentHash();
   }
   if (agent === 'cursor') {
-    return contentHash(
-      [CURSOR_RULES_CONTENT, ...slashCommandFiles('cursor').map(file => file.content)].join('\n')
-    );
+    return contentHashForDirectory(cursorSourcePluginDir());
   }
   if (agent === 'gemini') {
     return contentHash(slashCommandFiles('gemini').map(file => file.content).join('\n'));
@@ -508,6 +508,14 @@ function claudeSourcePluginDir() {
   );
 }
 
+function cursorSourcePluginDir() {
+  if (fs.existsSync(PACKAGE_CURSOR_PLUGIN_DIR)) return PACKAGE_CURSOR_PLUGIN_DIR;
+  if (fs.existsSync(REPO_CURSOR_PLUGIN_DIR)) return REPO_CURSOR_PLUGIN_DIR;
+  throw new Error(
+    `Cursor plugin bundle not found. Checked ${PACKAGE_CURSOR_PLUGIN_DIR} and ${REPO_CURSOR_PLUGIN_DIR}.`
+  );
+}
+
 function listFilesRecursive(dir) {
   if (!fs.existsSync(dir)) return [];
   return fs.readdirSync(dir, { withFileTypes: true }).flatMap(entry => {
@@ -731,6 +739,8 @@ function openCodePaths() {
 function cursorPaths() {
   const base = path.join(os.homedir(), '.cursor');
   return {
+    pluginDir: path.join(base, 'plugins', 'local', 'overlord'),
+    pluginManifest: path.join(base, 'plugins', 'local', 'overlord', '.cursor-plugin', 'plugin.json'),
     rulesFile: path.join(base, 'rules', 'overlord-local.mdc'),
     settingsFile: path.join(base, 'settings.json')
   };
@@ -870,10 +880,21 @@ function installCodex() {
 
 function installCursor() {
   const paths = cursorPaths();
-  writeTextFile(paths.rulesFile, CURSOR_RULES_CONTENT);
-  console.log(`  ✓ Installed rules: ${paths.rulesFile}`);
-
-  const slashResult = installSlashCommands('cursor');
+  const sourceDir = cursorSourcePluginDir();
+  fs.mkdirSync(path.dirname(paths.pluginDir), { recursive: true });
+  fs.rmSync(paths.pluginDir, { recursive: true, force: true });
+  fs.cpSync(sourceDir, paths.pluginDir, { recursive: true });
+  console.log(`  ✓ Installed plugin: ${paths.pluginDir}`);
+
+  if (fs.existsSync(paths.rulesFile)) {
+    fs.rmSync(paths.rulesFile, { force: true });
+    console.log(`  ✓ Removed legacy rules file: ${paths.rulesFile}`);
+  }
+  const removedLegacySlash = uninstallSlashCommands('cursor');
+  if (removedLegacySlash.removedFiles.length > 0) {
+    console.log('  ✓ Removed legacy slash commands:');
+    for (const filePath of removedLegacySlash.removedFiles) console.log(`      ${filePath}`);
+  }
 
   const existingSettings = readJsonFile(paths.settingsFile);
   const permissions =
@@ -898,10 +919,10 @@ function installCursor() {
 
   const manifest = readManifest();
   manifest.cursor = {
-    version: BUNDLE_VERSION,
+    version: pluginVersion(paths.pluginManifest) ?? '0.0.0',
     contentHash: currentContentHashForAgent('cursor'),
     installedAt: new Date().toISOString(),
-    files: [paths.rulesFile, paths.settingsFile, ...slashResult.managedFiles]
+    files: [...listFilesRecursive(paths.pluginDir), paths.settingsFile]
   };
   writeManifest(manifest);
 
@@ -958,8 +979,10 @@ function doctorAgent(agent) {
     agent === 'claude'
       ? pluginVersion(path.join(claudeSourcePluginDir(), '.claude-plugin', 'plugin.json'))
       : agent === 'codex'
-      ? pluginVersion(path.join(codexSourcePluginDir(), '.codex-plugin', 'plugin.json'))
-      : BUNDLE_VERSION;
+        ? pluginVersion(path.join(codexSourcePluginDir(), '.codex-plugin', 'plugin.json'))
+        : agent === 'cursor'
+          ? pluginVersion(path.join(cursorSourcePluginDir(), '.cursor-plugin', 'plugin.json'))
+          : BUNDLE_VERSION;
   const currentHash = currentContentHashForAgent(agent);
 
   if (entry.version !== currentVersion || entry.contentHash !== currentHash) {
@@ -1382,7 +1405,7 @@ export async function runSetupCommand(args) {
   ovld setup           Interactive setup (select agents and configure permissions)
   ovld setup claude    Prepare the Overlord Claude plugin and migrate v3.25 connector files
   ovld setup codex     Install Overlord Codex plugin bundle
-  ovld setup cursor    Install Overlord rules, slash commands, and permissions for Cursor
+  ovld setup cursor    Install Overlord Cursor local plugin and permissions
   ovld setup gemini    Install Overlord slash commands and policy rules for Gemini CLI
   ovld setup opencode  Install Overlord connector for OpenCode
   ovld setup all       Prepare all supported agents

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "overlord-cli",
-  "version": "4.1.0",
+  "version": "4.5.0",
   "description": "Overlord CLI — launch AI agents on tickets from anywhere",
   "type": "module",
   "bin": {

package/plugins/claude/README.md

@@ -4,7 +4,7 @@ Claude Code plugin that exposes the Overlord local ticket workflow to any Claude
 
 ## What ships
 
-- `skills/overlord-ticket-workflow/SKILL.md` — durable attach → update → ask → deliver workflow.
+- `skills/overlord-ticket/SKILL.md` — durable attach → update → ask → deliver workflow.
 - `commands/{connect,load,spawn}.md` — slash commands for session routing and ticket creation.
 - `hooks/hooks.json` + `scripts/permission-hook.sh` — PermissionRequest notifier that posts to `/api/protocol/permission-request` on the Overlord platform.
 - `userConfig` for `overlord_url` (non-sensitive) and `agent_token` (sensitive → OS keychain) so the hook and CLI know where to talk.
@@ -35,7 +35,7 @@ The plugin prompts for `overlord_url` and `agent_token` at install time. The tok
 
 Inside Claude Code the components are surfaced with the plugin prefix:
 
-- skill → `overlord:overlord-ticket-workflow`
+- skill → `overlord:overlord-ticket`
 - commands → `/overlord:connect`, `/overlord:load`, `/overlord:spawn`
 
 Prompts generated by Overlord (see `lib/overlord/ticket-prompt.ts`) already reference these names in `bundle` instruction mode.

package/plugins/claude/skills/{overlord-ticket-workflow → overlord-ticket}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: overlord-ticket-workflow
+name: overlord-ticket
 description: Overlord local workflow protocol — attach, update, deliver lifecycle for ticket-driven work from Claude Code.
 ---
 
-# Overlord Local Workflow
+# Overlord Ticket
 
 If you receive a prompt with a specified ticket ID, adhere to the following. If the prompt does not have a ticket ID, the user may choose to add one later, but otherwise, proceed without it.
 

package/plugins/cursor/.cursor-plugin/plugin.json

@@ -0,0 +1,14 @@
+{
+  "name": "overlord",
+  "version": "0.1.0",
+  "description": "Local Overlord workflow plugin for Cursor terminal agents.",
+  "author": {
+    "name": "Cooperativ",
+    "url": "https://github.com/cooperativ"
+  },
+  "homepage": "https://github.com/cooperativ/overlord",
+  "repository": "https://github.com/cooperativ/overlord",
+  "license": "UNLICENSED",
+  "skills": "./skills/",
+  "mcpServers": "./mcp.json"
+}

package/plugins/cursor/commands/connect.md

@@ -0,0 +1 @@
+Run `ovld protocol connect --ticket-id <ticketId>` using the text after `/connect`.

package/plugins/cursor/commands/load.md

@@ -0,0 +1 @@
+Run `ovld protocol load-context --ticket-id <ticketId>` using the text after `/load`.

package/plugins/cursor/commands/spawn.md

@@ -0,0 +1 @@
+Run `ovld protocol spawn --agent cursor --objective "<objective>"` using text after `/spawn` unless raw flags were provided.

package/plugins/cursor/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "overlord": {
+      "command": "node",
+      "args": ["./scripts/overlord-mcp.mjs"]
+    }
+  }
+}

package/plugins/cursor/rules/overlord-local.mdc

@@ -0,0 +1,8 @@
+---
+description: Overlord local workflow protocol for Cursor.
+alwaysApply: true
+---
+
+# Overlord Local Workflow
+
+Attach first, update during work, ask when blocked, and deliver last using `ovld protocol` commands.

package/plugins/cursor/scripts/overlord-mcp.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+const OVLD_BIN = process.env.OVLD_BIN?.trim() || 'ovld';
+const PROTOCOL_VERSION = '2025-06-18';
+let buffer = Buffer.alloc(0);
+
+function send(message) {
+  const json = JSON.stringify(message);
+  const body = Buffer.from(json, 'utf8');
+  const header = Buffer.from(`Content-Length: ${body.length}\r\n\r\n`, 'utf8');
+  process.stdout.write(Buffer.concat([header, body]));
+}
+
+function parseMessages(chunk) {
+  buffer = Buffer.concat([buffer, chunk]);
+  const messages = [];
+  while (true) {
+    const headerEnd = buffer.indexOf('\r\n\r\n');
+    if (headerEnd === -1) break;
+    const headerText = buffer.subarray(0, headerEnd).toString('utf8');
+    const lengthMatch = headerText.match(/Content-Length:\s*(\d+)/i);
+    if (!lengthMatch) throw new Error('Missing Content-Length header');
+    const contentLength = Number(lengthMatch[1]);
+    const totalLength = headerEnd + 4 + contentLength;
+    if (buffer.length < totalLength) break;
+    const body = buffer.subarray(headerEnd + 4, totalLength).toString('utf8');
+    buffer = buffer.subarray(totalLength);
+    messages.push(JSON.parse(body));
+  }
+  return messages;
+}
+
+async function runProtocol(subcommand, args = {}) {
+  const flags = Object.entries(args).flatMap(([key, value]) => {
+    if (value === undefined || value === null) return [];
+    if (typeof value === 'boolean') return value ? [`--${key}`] : [];
+    if (Array.isArray(value)) return [`--${key}`, JSON.stringify(value)];
+    if (typeof value === 'object') return [`--${key}-json`, JSON.stringify(value)];
+    return [`--${key}`, String(value)];
+  });
+
+  try {
+    const { stdout } = await execFileAsync(OVLD_BIN, ['protocol', subcommand, ...flags], {
+      env: {
+        ...process.env,
+        AGENT_IDENTIFIER: process.env.AGENT_IDENTIFIER ?? 'cursor-overlord-plugin'
+      },
+      maxBuffer: 20 * 1024 * 1024
+    });
+    const data = stdout.trim() ? JSON.parse(stdout) : {};
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }], structuredContent: data };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { content: [{ type: 'text', text: message }], isError: true };
+  }
+}
+
+process.stdin.on('data', async chunk => {
+  for (const message of parseMessages(chunk)) {
+    if (!message || typeof message !== 'object' || !('id' in message)) continue;
+    if (message.method === 'initialize') {
+      send({
+        jsonrpc: '2.0',
+        id: message.id,
+        result: {
+          protocolVersion: PROTOCOL_VERSION,
+          capabilities: { tools: { listChanged: false } },
+          serverInfo: { name: 'overlord-cursor', version: '0.1.0' }
+        }
+      });
+      continue;
+    }
+    if (message.method === 'tools/list') {
+      send({
+        jsonrpc: '2.0',
+        id: message.id,
+        result: {
+          tools: [
+            {
+              name: 'attach_ticket',
+              description: 'Attach to an Overlord ticket.',
+              inputSchema: { type: 'object', properties: { ticket_id: { type: 'string' } }, required: ['ticket_id'] }
+            },
+            {
+              name: 'post_update',
+              description: 'Post a progress update.',
+              inputSchema: {
+                type: 'object',
+                properties: { session_key: { type: 'string' }, ticket_id: { type: 'string' }, summary: { type: 'string' } },
+                required: ['session_key', 'ticket_id', 'summary']
+              }
+            },
+            {
+              name: 'deliver_ticket',
+              description: 'Deliver completed work.',
+              inputSchema: {
+                type: 'object',
+                properties: { session_key: { type: 'string' }, ticket_id: { type: 'string' }, summary: { type: 'string' } },
+                required: ['session_key', 'ticket_id', 'summary']
+              }
+            }
+          ]
+        }
+      });
+      continue;
+    }
+    if (message.method === 'tools/call') {
+      const toolName = message.params?.name;
+      const args = message.params?.arguments ?? {};
+      if (toolName === 'attach_ticket') {
+        send({ jsonrpc: '2.0', id: message.id, result: await runProtocol('attach', { 'ticket-id': args.ticket_id }) });
+      } else if (toolName === 'post_update') {
+        send({
+          jsonrpc: '2.0',
+          id: message.id,
+          result: await runProtocol('update', {
+            'session-key': args.session_key,
+            'ticket-id': args.ticket_id,
+            summary: args.summary,
+            phase: 'execute'
+          })
+        });
+      } else if (toolName === 'deliver_ticket') {
+        send({
+          jsonrpc: '2.0',
+          id: message.id,
+          result: await runProtocol('deliver', {
+            'session-key': args.session_key,
+            'ticket-id': args.ticket_id,
+            summary: args.summary
+          })
+        });
+      } else {
+        send({ jsonrpc: '2.0', id: message.id, error: { code: -32602, message: `Unknown tool: ${toolName}` } });
+      }
+      continue;
+    }
+    if (message.method === 'ping') {
+      send({ jsonrpc: '2.0', id: message.id, result: {} });
+      continue;
+    }
+    send({ jsonrpc: '2.0', id: message.id, error: { code: -32601, message: `Method not found: ${message.method}` } });
+  }
+});
+
+process.stdin.resume();

package/plugins/cursor/skills/overlord-ticket/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: overlord-ticket
+description: Durable local workflow for Overlord tickets from Cursor.
+---
+
+# Overlord Ticket
+
+Attach first with `ovld protocol attach --ticket-id <ticket-id>`, keep the `sessionKey`, post updates during implementation, and deliver last with change rationales.

package/plugins/overlord/README.md

@@ -30,7 +30,7 @@ The MCP server shells into the installed `ovld` binary so the plugin stays align
 
 ## Skill coverage
 
-- `skills/overlord-ticket-workflow/SKILL.md` teaches Codex the durable local workflow:
+- `skills/overlord-ticket/SKILL.md` teaches Codex the durable local workflow:
   attach first, update during work, ask when blocked, and deliver last.
 
 ## App surface status

package/plugins/overlord/skills/{overlord-ticket-workflow → overlord-ticket}/SKILL.md

@@ -1,4 +1,4 @@
-# Overlord Ticket Workflow
+# Overlord Ticket
 
 Use this skill when the user wants to work on an Overlord ticket from Codex through the local
 Overlord plugin.