Add Cursor CLI as target provider (#179)

* feat(cursor): add Cursor CLI as target provider

Add converter, writer, types, and tests for converting Claude Code
plugins to Cursor-compatible format (.mdc rules, commands, skills,
mcp.json). Agents become Agent Requested rules (alwaysApply: false),
commands are plain markdown, skills copy directly, MCP is 1:1 JSON.

* docs: add Cursor spec and update README with cursor target

* chore: bump CLI version to 0.5.0 for cursor target

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: note Cursor IDE + CLI compatibility in README

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

src/commands/convert.ts

@@ -22,7 +22,7 @@ export default defineCommand({
     to: {
       type: "string",
       default: "opencode",
-      description: "Target format (opencode | codex | droid)",
+      description: "Target format (opencode | codex | droid | cursor)",
     },
     output: {
       type: "string",
@@ -156,5 +156,6 @@ function resolveOutputRoot(value: unknown): string {
 function resolveTargetOutputRoot(targetName: string, outputRoot: string, codexHome: string): string {
   if (targetName === "codex") return codexHome
   if (targetName === "droid") return path.join(os.homedir(), ".factory")
+  if (targetName === "cursor") return path.join(outputRoot, ".cursor")
   return outputRoot
 }

src/commands/install.ts

@@ -24,7 +24,7 @@ export default defineCommand({
     to: {
       type: "string",
       default: "opencode",
-      description: "Target format (opencode | codex | droid)",
+      description: "Target format (opencode | codex | droid | cursor)",
     },
     output: {
       type: "string",
@@ -181,6 +181,7 @@ function resolveOutputRoot(value: unknown): string {
 function resolveTargetOutputRoot(targetName: string, outputRoot: string, codexHome: string): string {
   if (targetName === "codex") return codexHome
   if (targetName === "droid") return path.join(os.homedir(), ".factory")
+  if (targetName === "cursor") return path.join(outputRoot, ".cursor")
   return outputRoot
 }
 

src/converters/claude-to-cursor.ts

@@ -0,0 +1,166 @@
+import { formatFrontmatter } from "../utils/frontmatter"
+import type { ClaudeAgent, ClaudeCommand, ClaudeMcpServer, ClaudePlugin } from "../types/claude"
+import type { CursorBundle, CursorCommand, CursorMcpServer, CursorRule } from "../types/cursor"
+import type { ClaudeToOpenCodeOptions } from "./claude-to-opencode"
+
+export type ClaudeToCursorOptions = ClaudeToOpenCodeOptions
+
+export function convertClaudeToCursor(
+  plugin: ClaudePlugin,
+  _options: ClaudeToCursorOptions,
+): CursorBundle {
+  const usedRuleNames = new Set<string>()
+  const usedCommandNames = new Set<string>()
+
+  const rules = plugin.agents.map((agent) => convertAgentToRule(agent, usedRuleNames))
+  const commands = plugin.commands.map((command) => convertCommand(command, usedCommandNames))
+  const skillDirs = plugin.skills.map((skill) => ({
+    name: skill.name,
+    sourceDir: skill.sourceDir,
+  }))
+
+  const mcpServers = convertMcpServers(plugin.mcpServers)
+
+  if (plugin.hooks && Object.keys(plugin.hooks.hooks).length > 0) {
+    console.warn("Warning: Cursor does not support hooks. Hooks were skipped during conversion.")
+  }
+
+  return { rules, commands, skillDirs, mcpServers }
+}
+
+function convertAgentToRule(agent: ClaudeAgent, usedNames: Set<string>): CursorRule {
+  const name = uniqueName(normalizeName(agent.name), usedNames)
+  const description = agent.description ?? `Converted from Claude agent ${agent.name}`
+
+  const frontmatter: Record<string, unknown> = {
+    description,
+    alwaysApply: false,
+  }
+
+  let body = transformContentForCursor(agent.body.trim())
+  if (agent.capabilities && agent.capabilities.length > 0) {
+    const capabilities = agent.capabilities.map((c) => `- ${c}`).join("\n")
+    body = `## Capabilities\n${capabilities}\n\n${body}`.trim()
+  }
+  if (body.length === 0) {
+    body = `Instructions converted from the ${agent.name} agent.`
+  }
+
+  const content = formatFrontmatter(frontmatter, body)
+  return { name, content }
+}
+
+function convertCommand(command: ClaudeCommand, usedNames: Set<string>): CursorCommand {
+  const name = uniqueName(flattenCommandName(command.name), usedNames)
+
+  const sections: string[] = []
+
+  if (command.description) {
+    sections.push(`<!-- ${command.description} -->`)
+  }
+
+  if (command.argumentHint) {
+    sections.push(`## Arguments\n${command.argumentHint}`)
+  }
+
+  const transformedBody = transformContentForCursor(command.body.trim())
+  sections.push(transformedBody)
+
+  const content = sections.filter(Boolean).join("\n\n").trim()
+  return { name, content }
+}
+
+/**
+ * Transform Claude Code content to Cursor-compatible content.
+ *
+ * 1. Task agent calls: Task agent-name(args) -> Use the agent-name skill to: args
+ * 2. Slash commands: /workflows:plan -> /plan (flatten namespace)
+ * 3. Path rewriting: .claude/ -> .cursor/
+ * 4. Agent references: @agent-name -> the agent-name rule
+ */
+export function transformContentForCursor(body: string): string {
+  let result = body
+
+  // 1. Transform Task agent calls
+  const taskPattern = /^(\s*-?\s*)Task\s+([a-z][a-z0-9-]*)\(([^)]+)\)/gm
+  result = result.replace(taskPattern, (_match, prefix: string, agentName: string, args: string) => {
+    const skillName = normalizeName(agentName)
+    return `${prefix}Use the ${skillName} skill to: ${args.trim()}`
+  })
+
+  // 2. Transform slash command references (flatten namespaces)
+  const slashCommandPattern = /(?<![:\w])\/([a-z][a-z0-9_:-]*?)(?=[\s,."')\]}`]|$)/gi
+  result = result.replace(slashCommandPattern, (match, commandName: string) => {
+    if (commandName.includes("/")) return match
+    if (["dev", "tmp", "etc", "usr", "var", "bin", "home"].includes(commandName)) return match
+    const flattened = flattenCommandName(commandName)
+    return `/${flattened}`
+  })
+
+  // 3. Rewrite .claude/ paths to .cursor/
+  result = result
+    .replace(/~\/\.claude\//g, "~/.cursor/")
+    .replace(/\.claude\//g, ".cursor/")
+
+  // 4. Transform @agent-name references
+  const agentRefPattern = /@([a-z][a-z0-9-]*-(?:agent|reviewer|researcher|analyst|specialist|oracle|sentinel|guardian|strategist))/gi
+  result = result.replace(agentRefPattern, (_match, agentName: string) => {
+    return `the ${normalizeName(agentName)} rule`
+  })
+
+  return result
+}
+
+function convertMcpServers(
+  servers?: Record<string, ClaudeMcpServer>,
+): Record<string, CursorMcpServer> | undefined {
+  if (!servers || Object.keys(servers).length === 0) return undefined
+
+  const result: Record<string, CursorMcpServer> = {}
+  for (const [name, server] of Object.entries(servers)) {
+    const entry: CursorMcpServer = {}
+    if (server.command) {
+      entry.command = server.command
+      if (server.args && server.args.length > 0) entry.args = server.args
+      if (server.env && Object.keys(server.env).length > 0) entry.env = server.env
+    } else if (server.url) {
+      entry.url = server.url
+      if (server.headers && Object.keys(server.headers).length > 0) entry.headers = server.headers
+    }
+    result[name] = entry
+  }
+  return result
+}
+
+function flattenCommandName(name: string): string {
+  const colonIndex = name.lastIndexOf(":")
+  const base = colonIndex >= 0 ? name.slice(colonIndex + 1) : name
+  return normalizeName(base)
+}
+
+function normalizeName(value: string): string {
+  const trimmed = value.trim()
+  if (!trimmed) return "item"
+  const normalized = trimmed
+    .toLowerCase()
+    .replace(/[\\/]+/g, "-")
+    .replace(/[:\s]+/g, "-")
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-+|-+$/g, "")
+  return normalized || "item"
+}
+
+function uniqueName(base: string, used: Set<string>): string {
+  if (!used.has(base)) {
+    used.add(base)
+    return base
+  }
+  let index = 2
+  while (used.has(`${base}-${index}`)) {
+    index += 1
+  }
+  const name = `${base}-${index}`
+  used.add(name)
+  return name
+}

src/targets/cursor.ts

@@ -0,0 +1,48 @@
+import path from "path"
+import { backupFile, copyDir, ensureDir, writeJson, writeText } from "../utils/files"
+import type { CursorBundle } from "../types/cursor"
+
+export async function writeCursorBundle(outputRoot: string, bundle: CursorBundle): Promise<void> {
+  const paths = resolveCursorPaths(outputRoot)
+  await ensureDir(paths.cursorDir)
+
+  if (bundle.rules.length > 0) {
+    const rulesDir = path.join(paths.cursorDir, "rules")
+    for (const rule of bundle.rules) {
+      await writeText(path.join(rulesDir, `${rule.name}.mdc`), rule.content + "\n")
+    }
+  }
+
+  if (bundle.commands.length > 0) {
+    const commandsDir = path.join(paths.cursorDir, "commands")
+    for (const command of bundle.commands) {
+      await writeText(path.join(commandsDir, `${command.name}.md`), command.content + "\n")
+    }
+  }
+
+  if (bundle.skillDirs.length > 0) {
+    const skillsDir = path.join(paths.cursorDir, "skills")
+    for (const skill of bundle.skillDirs) {
+      await copyDir(skill.sourceDir, path.join(skillsDir, skill.name))
+    }
+  }
+
+  if (bundle.mcpServers && Object.keys(bundle.mcpServers).length > 0) {
+    const mcpPath = path.join(paths.cursorDir, "mcp.json")
+    const backupPath = await backupFile(mcpPath)
+    if (backupPath) {
+      console.log(`Backed up existing mcp.json to ${backupPath}`)
+    }
+    await writeJson(mcpPath, { mcpServers: bundle.mcpServers })
+  }
+}
+
+function resolveCursorPaths(outputRoot: string) {
+  const base = path.basename(outputRoot)
+  // If already pointing at .cursor, write directly into it
+  if (base === ".cursor") {
+    return { cursorDir: outputRoot }
+  }
+  // Otherwise nest under .cursor
+  return { cursorDir: path.join(outputRoot, ".cursor") }
+}

src/targets/index.ts

@@ -2,12 +2,15 @@ import type { ClaudePlugin } from "../types/claude"
 import type { OpenCodeBundle } from "../types/opencode"
 import type { CodexBundle } from "../types/codex"
 import type { DroidBundle } from "../types/droid"
+import type { CursorBundle } from "../types/cursor"
 import { convertClaudeToOpenCode, type ClaudeToOpenCodeOptions } from "../converters/claude-to-opencode"
 import { convertClaudeToCodex } from "../converters/claude-to-codex"
 import { convertClaudeToDroid } from "../converters/claude-to-droid"
+import { convertClaudeToCursor } from "../converters/claude-to-cursor"
 import { writeOpenCodeBundle } from "./opencode"
 import { writeCodexBundle } from "./codex"
 import { writeDroidBundle } from "./droid"
+import { writeCursorBundle } from "./cursor"
 
 export type TargetHandler<TBundle = unknown> = {
   name: string
@@ -35,4 +38,10 @@ export const targets: Record<string, TargetHandler> = {
     convert: convertClaudeToDroid as TargetHandler<DroidBundle>["convert"],
     write: writeDroidBundle as TargetHandler<DroidBundle>["write"],
   },
+  cursor: {
+    name: "cursor",
+    implemented: true,
+    convert: convertClaudeToCursor as TargetHandler<CursorBundle>["convert"],
+    write: writeCursorBundle as TargetHandler<CursorBundle>["write"],
+  },
 }

src/types/cursor.ts

@@ -0,0 +1,29 @@
+export type CursorRule = {
+  name: string
+  content: string
+}
+
+export type CursorCommand = {
+  name: string
+  content: string
+}
+
+export type CursorSkillDir = {
+  name: string
+  sourceDir: string
+}
+
+export type CursorMcpServer = {
+  command?: string
+  args?: string[]
+  env?: Record<string, string>
+  url?: string
+  headers?: Record<string, string>
+}
+
+export type CursorBundle = {
+  rules: CursorRule[]
+  commands: CursorCommand[]
+  skillDirs: CursorSkillDir[]
+  mcpServers?: Record<string, CursorMcpServer>
+}