@fatdoge/wtree 0.1.10 → 0.2.0

package/README.en.md

@@ -11,8 +11,21 @@ English | [简体中文](https://github.com/FatDoge/wtree/blob/main/README.md)
 - Support for creating worktrees from new branches or existing branches/commits
 - Open worktrees instantly in your system file manager or preferred IDEs (Trae, Cursor, VS Code)
 - Support for Locking, Unlocking, and Pruning invalid worktrees
+- Non-interactive mode: fully automated operations via CLI flags, ideal for scripts and AI Agents
+- Provides Agent Skill for AI coding tools like Trae, Cursor, and Claude Code
 - Local API executes git commands securely on your machine, data never leaves your computer
 
+## Screenshots
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/FatDoge/wtree/main/docs/screenshots/home.jpg" alt="Home" width="48%" />
+  <img src="https://raw.githubusercontent.com/FatDoge/wtree/main/docs/screenshots/new.jpg" alt="Create" width="48%" />
+</p>
+<p align="center">
+  <img src="https://raw.githubusercontent.com/FatDoge/wtree/main/docs/screenshots/settings.jpg" alt="Settings" width="48%" />
+  <img src="https://raw.githubusercontent.com/FatDoge/wtree/main/docs/screenshots/help.jpg" alt="Help" width="48%" />
+</p>
+
 ## Installation
 
 Install globally via npm (specify the public registry if you are using a private one):
@@ -68,7 +81,7 @@ wtree --ui --port 0
 - `wtree`: Interactive main menu (Create/Delete/List/Open/Lock/Unlock/Prune)
 - `wtree list`: Print worktree list
 - `wtree create [branch]`: Create a worktree (interactive selection supported)
-- `wtree delete`: Delete a worktree (interactive selection, force deletion supported)
+- `wtree delete [branch|path ...]`: Delete worktrees (interactive selection or specify targets directly, force deletion supported)
 - `wtree open [path|branch]`: Open a worktree
 - `wtree lock [path|branch]`: Lock a specific worktree to prevent it from being moved or deleted
 - `wtree unlock [path|branch]`: Unlock a specific worktree
@@ -78,6 +91,58 @@ wtree --ui --port 0
 - `wtree config set <key> <value>`: Set a configuration item
 - `wtree help`: View help information
 
+## CLI Flags
+
+- `--ui`: Launch the local UI
+- `--repo <path>`: Specify the repository path (defaults to the current directory)
+- `--no-open`: Do not automatically open the browser
+- `--port <number>`: Specify the UI port (`0` for auto-assign)
+- `--json`: Output in JSON format (ideal for scripts and AI Agents)
+- `--yes, -y`: Auto-confirm all prompts
+- `--force, -f`: Force the operation (e.g., force-delete worktrees with uncommitted changes)
+- `--dir <path>`: Specify worktree directory path (relative to the git root)
+- `--base <ref>`: Base reference for new branch creation (e.g., `main`, `origin/main`)
+- `--editor <name>`: Open in a specific editor after creation (`trae`, `cursor`, `code`, `none`)
+- `--no-editor`: Do not open any editor after creation
+- `--no-install`: Skip automatic dependency installation after creation
+
+## Non-Interactive Mode
+
+All commands support fully non-interactive execution via CLI flags, suitable for scripts and AI Agents:
+
+```bash
+# List worktrees (JSON output)
+wtree list --json
+
+# Create a worktree for an existing branch
+wtree create feature/my-branch --yes --no-editor --no-install --json
+
+# Create a worktree with a new branch based on main
+wtree create feature/new-thing --base main --yes --dir worktrees/new-thing --no-editor --no-install --json
+
+# Delete a specific worktree
+wtree delete feature/old-branch --yes --json
+
+# Force delete (even with uncommitted changes)
+wtree delete feature/dirty --yes --force --json
+```
+
+## Agent Skill
+
+`wtree` provides an Agent Skill that enables AI coding tools (Trae, Cursor, Claude Code, etc.) to manage git worktrees directly.
+
+### Install Skill
+
+```bash
+# Install to current project
+npx skills add FatDoge/wtree --skill wtree
+
+# Install globally (available in all projects)
+npx skills add FatDoge/wtree --skill wtree -g
+```
+
+Once installed, the AI Agent will automatically recognize the `wtree` skill and invoke it when you need to manage worktrees.
+
 ## Configuration
 
 The UI settings page saves configuration to a local file:

package/README.md

@@ -11,8 +11,21 @@
 - 支持创建新分支、从已有分支/提交创建 worktree
 - 支持在系统文件管理器或常用 IDE (Trae, Cursor, VS Code) 中一键打开
 - 支持锁定 (Lock) / 解锁 (Unlock) 以及清理 (Prune) 无效的 worktree
+- 非交互模式：支持通过命令行参数完全自动化操作，适合脚本和 AI Agent 调用
+- 提供 Agent Skill，可被 Trae / Cursor / Claude Code 等 AI 编码工具直接使用
 - 本地 API 执行 git 命令，数据不出机器
 
+## UI 截图
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/FatDoge/wtree/main/docs/screenshots/home.jpg" alt="首页" width="48%" />
+  <img src="https://raw.githubusercontent.com/FatDoge/wtree/main/docs/screenshots/new.jpg" alt="创建页面" width="48%" />
+</p>
+<p align="center">
+  <img src="https://raw.githubusercontent.com/FatDoge/wtree/main/docs/screenshots/settings.jpg" alt="设置页面" width="48%" />
+  <img src="https://raw.githubusercontent.com/FatDoge/wtree/main/docs/screenshots/help.jpg" alt="帮助页面" width="48%" />
+</p>
+
 ## 安装
 
 可以通过 npm 全局安装（如果使用了私有源，请指定官方源）：
@@ -69,13 +82,21 @@ wtree --ui --port 0
 - `--repo <path>`：指定仓库路径（默认使用当前目录）
 - `--no-open`：不自动打开浏览器
 - `--port <number>`：指定 UI 端口（`0` 表示自动分配）
+- `--json`：以 JSON 格式输出（适合脚本和 Agent 使用）
+- `--yes, -y`：自动确认所有提示
+- `--force, -f`：强制操作（如强制删除有未提交更改的 worktree）
+- `--dir <path>`：指定 worktree 目录路径（相对于 git 根目录）
+- `--base <ref>`：创建新分支时的基准引用（如 `main`、`origin/main`）
+- `--editor <name>`：创建后使用指定编辑器打开（`trae`、`cursor`、`code`、`none`）
+- `--no-editor`：创建后不打开编辑器
+- `--no-install`：创建后不自动安装依赖
 
 ## CLI 命令
 
 - `wtree`：交互式主菜单 (创建/删除/列表/打开/锁定/解锁/清理)
 - `wtree list`：打印 worktree 列表
 - `wtree create [branch]`：创建 worktree（支持交互式选择）
-- `wtree delete`：删除 worktree（交互式选择，支持强制删除）
+- `wtree delete [branch|path ...]`：删除 worktree（支持交互式选择和直接指定目标，支持强制删除）
 - `wtree open [path|branch]`：打开 worktree
 - `wtree lock [path|branch]`：锁定指定的 worktree，防止被移动或删除
 - `wtree unlock [path|branch]`：解锁指定的 worktree
@@ -85,6 +106,43 @@ wtree --ui --port 0
 - `wtree config set <key> <value>`：设置配置项
 - `wtree help`：查看帮助
 
+## 非交互模式
+
+所有命令都支持通过参数完全非交互地执行，适合在脚本或 AI Agent 中使用：
+
+```bash
+# 查看 worktree 列表（JSON 输出）
+wtree list --json
+
+# 为已有分支创建 worktree
+wtree create feature/my-branch --yes --no-editor --no-install --json
+
+# 基于 main 创建新分支的 worktree
+wtree create feature/new-thing --base main --yes --dir worktrees/new-thing --no-editor --no-install --json
+
+# 删除指定 worktree
+wtree delete feature/old-branch --yes --json
+
+# 强制删除（即使有未提交更改）
+wtree delete feature/dirty --yes --force --json
+```
+
+## Agent Skill
+
+`wtree` 提供了 Agent Skill，可以让 AI 编码工具（Trae、Cursor、Claude Code 等）直接管理 git worktree。
+
+### 安装 Skill
+
+```bash
+# 安装到当前项目
+npx skills add FatDoge/wtree --skill wtree
+
+# 全局安装（所有项目可用）
+npx skills add FatDoge/wtree --skill wtree -g
+```
+
+安装后，AI Agent 会自动识别 `wtree` skill，在你需要管理 worktree 时自动调用。
+
 ## 配置
 
 UI 设置页会将配置写入本地文件：
@@ -137,3 +195,4 @@ pnpm run check
 - `api/`：CLI + 本地 API（git 执行与配置读写）
 - `src/`：UI（React + Vite + Tailwind）
 - `shared/`：前后端共享类型
+- `skills/`：Agent Skill 定义

package/api/cli/wtree.ts

@@ -13,8 +13,24 @@ import { openPath } from '../core/open.js'
 import { readConfig, writeConfig, getConfigPaths } from '../core/config.js'
 import { startUiDevServer } from '../ui/startUiDev.js'
 
+type ParsedFlags = {
+  ui: boolean
+  noOpen: boolean
+  repo: string
+  port: number | undefined
+  json: boolean
+  yes: boolean
+  force: boolean
+  dir: string
+  base: string
+  editor: string | undefined
+  noEditor: boolean
+  noInstall: boolean
+}
+
 type Ctx = {
   rootDir: string
+  flags: ParsedFlags
 }
 
 type SourceSelection =
@@ -33,11 +49,19 @@ function errMsg(e: unknown) {
 
 function parseArgs(argv: string[]) {
   const args = [...argv]
-  const flags = {
+  const flags: ParsedFlags = {
     ui: false,
     noOpen: false,
     repo: '',
     port: undefined as number | undefined,
+    json: false,
+    yes: false,
+    force: false,
+    dir: '',
+    base: '',
+    editor: undefined,
+    noEditor: false,
+    noInstall: false,
   }
   const positional: string[] = []
 
@@ -60,6 +84,14 @@ function parseArgs(argv: string[]) {
       if (Number.isFinite(v)) flags.port = v
       continue
     }
+    if (a === '--json') { flags.json = true; continue }
+    if (a === '--yes' || a === '-y') { flags.yes = true; continue }
+    if (a === '--force' || a === '-f') { flags.force = true; continue }
+    if (a === '--dir') { flags.dir = String(args.shift() || ''); continue }
+    if (a === '--base') { flags.base = String(args.shift() || ''); continue }
+    if (a === '--editor') { flags.editor = String(args.shift() || ''); continue }
+    if (a === '--no-editor') { flags.noEditor = true; continue }
+    if (a === '--no-install') { flags.noInstall = true; continue }
     if (a.startsWith('--')) continue
     positional.push(a)
   }
@@ -99,8 +131,12 @@ function parseCommand(positional: string[]) {
   return { command: 'interactive' as CommandType, rest: positional }
 }
 
-function printWorktreeList(rootDir: string) {
+function printWorktreeList(rootDir: string, json = false) {
   const items = listWorktrees(rootDir)
+  if (json) {
+    console.info(JSON.stringify(items, null, 2))
+    return
+  }
   if (items.length === 0) {
     console.info('未读取到 worktree。')
     return
@@ -118,7 +154,7 @@ function printHelp() {
   console.info('  wtree')
   console.info('  wtree list')
   console.info('  wtree create [branch]')
-  console.info('  wtree delete')
+  console.info('  wtree delete [branch|path ...]')
   console.info('  wtree open [path|branch]')
   console.info('  wtree lock [path|branch]')
   console.info('  wtree unlock [path|branch]')
@@ -128,7 +164,23 @@ function printHelp() {
   console.info('  wtree config set <key> <value>')
   console.info('  wtree --ui [--repo <path>] [--no-open] [--port <number>]')
   console.info('')
+  console.info('选项:')
+  console.info('  --json          以 JSON 格式输出 (适合脚本/agent 使用)')
+  console.info('  --yes, -y       自动确认所有提示')
+  console.info('  --force, -f     强制操作 (如强制删除有未提交更改的 worktree)')
+  console.info('  --dir <path>    指定 worktree 目录路径 (相对于 git 根目录)')
+  console.info('  --base <ref>    创建新分支时的基准引用 (如 main, origin/main)')
+  console.info('  --editor <name> 创建后使用指定编辑器打开 (trae, cursor, code, none)')
+  console.info('  --no-editor     创建后不打开编辑器')
+  console.info('  --no-install    创建后不自动安装依赖')
+  console.info('')
   console.info('可用配置 key: baseDir, openCommand, editorCommand')
+  console.info('')
+  console.info('非交互示例:')
+  console.info('  wtree list --json')
+  console.info('  wtree create feat/x --yes --no-editor --no-install --json')
+  console.info('  wtree create feat/new --base main --yes --dir worktrees/feat-new --json')
+  console.info('  wtree delete feat/old --yes --force --json')
 }
 
 function resolveWorktree(rootDir: string, key: string) {
@@ -312,21 +364,23 @@ async function main() {
     return
   }
 
-  console.info(chalk.blue(`检测到git repo根目录 ${rootDir}，将在这里运行git命令`))
+  if (!flags.json) {
+    console.info(chalk.blue(`检测到git repo根目录 ${rootDir}，将在这里运行git命令`))
+  }
 
   const { command, rest } = parseCommand(positional)
   if (command === 'list') {
-    printWorktreeList(rootDir)
+    printWorktreeList(rootDir, flags.json)
     return
   }
 
   if (command === 'create') {
-    await createWorktree({ rootDir }, rest[0])
+    await createWorktree({ rootDir, flags }, rest[0])
     return
   }
 
   if (command === 'delete') {
-    await deleteWorktree({ rootDir })
+    await deleteWorktree({ rootDir, flags }, rest)
     return
   }
 
@@ -376,7 +430,7 @@ async function main() {
   const directBranch = rest[0]
 
   const action = await getUserAction(directBranch)
-  const ctx: Ctx = { rootDir }
+  const ctx: Ctx = { rootDir, flags }
   if (action === 'create') {
     await createWorktree(ctx, directBranch)
   } else if (action === 'delete') {
@@ -416,7 +470,7 @@ async function getUserAction(directBranch?: string) {
 }
 
 async function createWorktree(ctx: Ctx, directBranch?: string) {
-  const { rootDir } = ctx
+  const { rootDir, flags } = ctx
   const defaultBranch =
     git(rootDir, ['symbolic-ref', '--short', 'refs/remotes/origin/HEAD']).stdout
       .replace(/^origin\//, '')
@@ -429,13 +483,16 @@ async function createWorktree(ctx: Ctx, directBranch?: string) {
     selection,
     directBranch,
     defaultBranch,
+    flags,
   )
-  const { targetDir, dirName } = await selectTargetDir(rootDir, targetBranch)
+  const { targetDir, dirName } = await selectTargetDir(rootDir, targetBranch, flags)
 
-  console.info(chalk.green(`\n准备创建 Worktree:`))
-  console.info(`  分支: ${targetBranch}`)
-  console.info(`  目录: ${targetDir}`)
-  console.info(`  来源: ${baseRef || 'Existing Local'}`)
+  if (!flags.json) {
+    console.info(chalk.green(`\n准备创建 Worktree:`))
+    console.info(`  分支: ${targetBranch}`)
+    console.info(`  目录: ${targetDir}`)
+    console.info(`  来源: ${baseRef || 'Existing Local'}`)
+  }
 
   await createGitWorktree(
     rootDir,
@@ -448,8 +505,14 @@ async function createWorktree(ctx: Ctx, directBranch?: string) {
   )
 
   await setupWorktreeEnv(rootDir, targetDir, dirName)
-  await installDependencies(targetDir)
-  await openInIDE(targetDir)
+  await installDependencies(targetDir, flags.noInstall)
+  await openInIDE(targetDir, flags)
+
+  if (flags.json) {
+    const items = listWorktrees(rootDir)
+    const created = items.find(x => path.resolve(x.path) === path.resolve(targetDir))
+    console.info(JSON.stringify({ ok: true, data: created || null }))
+  }
 }
 
 async function selectSource(rootDir: string, directBranch: string | undefined, defaultBranch: string) {
@@ -503,6 +566,7 @@ async function resolveBranchInfo(
   selection: SourceSelection,
   directBranch: string | undefined,
   defaultBranch: string,
+  flags: ParsedFlags,
 ) {
   let targetBranch = ''
   let baseRef = ''
@@ -541,19 +605,24 @@ async function resolveBranchInfo(
         baseRef = `origin/${targetBranch}`
         isNewBranch = true
       } else {
-        const { createNew } = await inquirer.prompt([
-          {
-            type: 'confirm',
-            name: 'createNew',
-            message: `分支 ${targetBranch} 不存在。是否基于 ${defaultBranch} 创建新分支?`,
-            default: true,
-          },
-        ])
-        if (createNew) {
-          baseRef = defaultBranch
+        if (flags.yes) {
+          baseRef = flags.base || defaultBranch
           isNewBranch = true
         } else {
-          process.exit(1)
+          const { createNew } = await inquirer.prompt([
+            {
+              type: 'confirm',
+              name: 'createNew',
+              message: `分支 ${targetBranch} 不存在。是否基于 ${defaultBranch} 创建新分支?`,
+              default: true,
+            },
+          ])
+          if (createNew) {
+            baseRef = defaultBranch
+            isNewBranch = true
+          } else {
+            process.exit(1)
+          }
         }
       }
     }
@@ -612,16 +681,25 @@ async function resolveBranchInfo(
   return { targetBranch, baseRef, isNewBranch }
 }
 
-async function selectTargetDir(rootDir: string, targetBranch: string) {
+async function selectTargetDir(rootDir: string, targetBranch: string, flags: ParsedFlags) {
   const defaultDirName = `worktrees/${targetBranch.split('/').join('-')}`
-  const { dirName } = await inquirer.prompt([
-    {
-      type: 'input',
-      name: 'dirName',
-      message: `请输入 Worktree 目录路径 (相对于 Git 根目录, 默认: ${defaultDirName}):`,
-      default: defaultDirName,
-    },
-  ])
+
+  let dirName: string
+  if (flags.dir) {
+    dirName = flags.dir
+  } else if (flags.yes) {
+    dirName = defaultDirName
+  } else {
+    const result = await inquirer.prompt([
+      {
+        type: 'input',
+        name: 'dirName',
+        message: `请输入 Worktree 目录路径 (相对于 Git 根目录, 默认: ${defaultDirName}):`,
+        default: defaultDirName,
+      },
+    ])
+    dirName = result.dirName
+  }
 
   const targetDir = path.resolve(rootDir, dirName)
   if (fs.existsSync(targetDir)) {
@@ -682,7 +760,8 @@ async function setupWorktreeEnv(rootDir: string, targetDir: string, dirName: str
   }
 }
 
-async function installDependencies(targetDir: string) {
+async function installDependencies(targetDir: string, skip = false) {
+  if (skip) return
   if (!fs.existsSync(path.join(targetDir, 'package.json'))) return
   try {
     execSync('pnpm --version', { stdio: 'ignore' })
@@ -702,7 +781,18 @@ function hasCommand(cmd: string) {
   }
 }
 
-async function openInIDE(targetDir: string) {
+async function openInIDE(targetDir: string, flags: ParsedFlags) {
+  if (flags.noEditor) return
+  if (flags.editor !== undefined) {
+    if (flags.editor === 'none' || flags.editor === '') return
+    try {
+      execSync(`${flags.editor} "${targetDir}"`, { stdio: 'ignore' })
+    } catch (e: unknown) {
+      void e
+    }
+    return
+  }
+
   const editors: { name: string; value: string }[] = []
   if (hasCommand('trae')) editors.push({ name: `在 Trae 中打开 （trae ${targetDir}）`, value: 'trae' })
   if (hasCommand('cursor')) editors.push({ name: `在 Cursor 中打开 （cursor ${targetDir}）`, value: 'cursor' })
@@ -729,35 +819,64 @@ async function openInIDE(targetDir: string) {
   }
 }
 
-async function deleteWorktree(ctx: Ctx) {
-  const worktrees = getWorktreeList(ctx.rootDir)
-  const choices = getDeletableWorktrees(ctx.rootDir, worktrees)
+async function deleteWorktree(ctx: Ctx, targets: string[] = []) {
+  const { rootDir, flags } = ctx
+  const worktrees = getWorktreeList(rootDir)
+  const choices = getDeletableWorktrees(rootDir, worktrees)
   if (choices.length === 0) {
-    console.warn(chalk.yellow('没有可删除的 Worktree (除了主 Worktree)'))
+    if (flags.json) {
+      console.info(JSON.stringify({ ok: true, data: [], message: 'No deletable worktrees' }))
+    } else {
+      console.warn(chalk.yellow('没有可删除的 Worktree (除了主 Worktree)'))
+    }
     return
   }
 
-  const { targetPaths } = await inquirer.prompt([
-    {
-      type: 'checkbox',
-      name: 'targetPaths',
-      message: '请选择要删除的 Worktree:',
-      choices,
-      validate: (answer: string[]) => (answer.length > 0 ? true : '请至少选择一个'),
-    },
-  ])
+  let targetPaths: string[]
+
+  if (targets.length > 0) {
+    // Non-interactive: resolve each target to a worktree path
+    targetPaths = []
+    for (const key of targets) {
+      const wt = resolveWorktree(rootDir, key)
+      if (!wt) {
+        console.error(chalk.red(`未找到 worktree: ${key}`))
+        process.exit(1)
+      }
+      if (path.resolve(wt.path) === path.resolve(rootDir)) {
+        console.error(chalk.red(`不能删除主 worktree: ${key}`))
+        process.exit(1)
+      }
+      targetPaths.push(wt.path)
+    }
+  } else {
+    // Interactive: checkbox prompt
+    const result = await inquirer.prompt([
+      {
+        type: 'checkbox',
+        name: 'targetPaths',
+        message: '请选择要删除的 Worktree:',
+        choices,
+        validate: (answer: string[]) => (answer.length > 0 ? true : '请至少选择一个'),
+      },
+    ])
+    targetPaths = result.targetPaths
+  }
+
+  if (!flags.yes) {
+    const { confirmDelete } = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'confirmDelete',
+        message: `确定要删除这 ${targetPaths.length} 个 Worktree 吗?`,
+        default: false,
+      },
+    ])
+    if (!confirmDelete) return
+  }
 
-  const { confirmDelete } = await inquirer.prompt([
-    {
-      type: 'confirm',
-      name: 'confirmDelete',
-      message: `确定要删除这 ${targetPaths.length} 个 Worktree 吗?`,
-      default: false,
-    },
-  ])
-  if (!confirmDelete) return
   for (const targetPath of targetPaths) {
-    await deleteSingleWorktree(ctx.rootDir, targetPath)
+    await deleteSingleWorktree(rootDir, targetPath, flags)
   }
 }
 
@@ -779,26 +898,47 @@ function getDeletableWorktrees(rootDir: string, worktrees: { path: string; branc
     })
 }
 
-async function deleteSingleWorktree(rootDir: string, targetPath: string) {
+async function deleteSingleWorktree(rootDir: string, targetPath: string, flags: ParsedFlags) {
   try {
     gitOrThrow(rootDir, ['worktree', 'remove', targetPath], 'WORKTREE_REMOVE')
-    console.info(chalk.green(`成功删除: ${targetPath}`))
+    if (flags.json) {
+      console.info(JSON.stringify({ ok: true, removed: targetPath }))
+    } else {
+      console.info(chalk.green(`成功删除: ${targetPath}`))
+    }
   } catch (e: unknown) {
-    console.error(chalk.red(`删除失败: ${errMsg(e)}`))
-    const { force } = await inquirer.prompt([
-      {
-        type: 'confirm',
-        name: 'force',
-        message: '删除失败 (可能有未提交的更改). 强制删除吗?',
-        default: false,
-      },
-    ])
-    if (!force) return
-    try {
-      gitOrThrow(rootDir, ['worktree', 'remove', '--force', targetPath], 'WORKTREE_REMOVE_FORCE')
-      console.info(chalk.green(`成功强制删除: ${targetPath}`))
-    } catch (forceErr: unknown) {
-      console.error(chalk.red(`强制删除也失败了: ${errMsg(forceErr)}`))
+    if (flags.force) {
+      try {
+        gitOrThrow(rootDir, ['worktree', 'remove', '--force', targetPath], 'WORKTREE_REMOVE_FORCE')
+        if (flags.json) {
+          console.info(JSON.stringify({ ok: true, removed: targetPath, forced: true }))
+        } else {
+          console.info(chalk.green(`成功强制删除: ${targetPath}`))
+        }
+      } catch (forceErr: unknown) {
+        if (flags.json) {
+          console.error(JSON.stringify({ ok: false, error: errMsg(forceErr), path: targetPath }))
+        } else {
+          console.error(chalk.red(`强制删除也失败了: ${errMsg(forceErr)}`))
+        }
+      }
+    } else {
+      console.error(chalk.red(`删除失败: ${errMsg(e)}`))
+      const { force } = await inquirer.prompt([
+        {
+          type: 'confirm',
+          name: 'force',
+          message: '删除失败 (可能有未提交的更改). 强制删除吗?',
+          default: false,
+        },
+      ])
+      if (!force) return
+      try {
+        gitOrThrow(rootDir, ['worktree', 'remove', '--force', targetPath], 'WORKTREE_REMOVE_FORCE')
+        console.info(chalk.green(`成功强制删除: ${targetPath}`))
+      } catch (forceErr: unknown) {
+        console.error(chalk.red(`强制删除也失败了: ${errMsg(forceErr)}`))
+      }
     }
   }
 }

package/dist-node/api/cli/wtree.js

@@ -21,6 +21,14 @@ function parseArgs(argv) {
         noOpen: false,
         repo: '',
         port: undefined,
+        json: false,
+        yes: false,
+        force: false,
+        dir: '',
+        base: '',
+        editor: undefined,
+        noEditor: false,
+        noInstall: false,
     };
     const positional = [];
     while (args.length) {
@@ -43,6 +51,38 @@ function parseArgs(argv) {
                 flags.port = v;
             continue;
         }
+        if (a === '--json') {
+            flags.json = true;
+            continue;
+        }
+        if (a === '--yes' || a === '-y') {
+            flags.yes = true;
+            continue;
+        }
+        if (a === '--force' || a === '-f') {
+            flags.force = true;
+            continue;
+        }
+        if (a === '--dir') {
+            flags.dir = String(args.shift() || '');
+            continue;
+        }
+        if (a === '--base') {
+            flags.base = String(args.shift() || '');
+            continue;
+        }
+        if (a === '--editor') {
+            flags.editor = String(args.shift() || '');
+            continue;
+        }
+        if (a === '--no-editor') {
+            flags.noEditor = true;
+            continue;
+        }
+        if (a === '--no-install') {
+            flags.noInstall = true;
+            continue;
+        }
         if (a.startsWith('--'))
             continue;
         positional.push(a);
@@ -80,8 +120,12 @@ function parseCommand(positional) {
     }
     return { command: 'interactive', rest: positional };
 }
-function printWorktreeList(rootDir) {
+function printWorktreeList(rootDir, json = false) {
     const items = listWorktrees(rootDir);
+    if (json) {
+        console.info(JSON.stringify(items, null, 2));
+        return;
+    }
     if (items.length === 0) {
         console.info('未读取到 worktree。');
         return;
@@ -98,7 +142,7 @@ function printHelp() {
     console.info('  wtree');
     console.info('  wtree list');
     console.info('  wtree create [branch]');
-    console.info('  wtree delete');
+    console.info('  wtree delete [branch|path ...]');
     console.info('  wtree open [path|branch]');
     console.info('  wtree lock [path|branch]');
     console.info('  wtree unlock [path|branch]');
@@ -108,7 +152,23 @@ function printHelp() {
     console.info('  wtree config set <key> <value>');
     console.info('  wtree --ui [--repo <path>] [--no-open] [--port <number>]');
     console.info('');
+    console.info('选项:');
+    console.info('  --json          以 JSON 格式输出 (适合脚本/agent 使用)');
+    console.info('  --yes, -y       自动确认所有提示');
+    console.info('  --force, -f     强制操作 (如强制删除有未提交更改的 worktree)');
+    console.info('  --dir <path>    指定 worktree 目录路径 (相对于 git 根目录)');
+    console.info('  --base <ref>    创建新分支时的基准引用 (如 main, origin/main)');
+    console.info('  --editor <name> 创建后使用指定编辑器打开 (trae, cursor, code, none)');
+    console.info('  --no-editor     创建后不打开编辑器');
+    console.info('  --no-install    创建后不自动安装依赖');
+    console.info('');
     console.info('可用配置 key: baseDir, openCommand, editorCommand');
+    console.info('');
+    console.info('非交互示例:');
+    console.info('  wtree list --json');
+    console.info('  wtree create feat/x --yes --no-editor --no-install --json');
+    console.info('  wtree create feat/new --base main --yes --dir worktrees/feat-new --json');
+    console.info('  wtree delete feat/old --yes --force --json');
 }
 function resolveWorktree(rootDir, key) {
     const items = listWorktrees(rootDir);
@@ -276,18 +336,20 @@ async function main() {
         process.on('SIGTERM', close);
         return;
     }
-    console.info(chalk.blue(`检测到git repo根目录 ${rootDir}，将在这里运行git命令`));
+    if (!flags.json) {
+        console.info(chalk.blue(`检测到git repo根目录 ${rootDir}，将在这里运行git命令`));
+    }
     const { command, rest } = parseCommand(positional);
     if (command === 'list') {
-        printWorktreeList(rootDir);
+        printWorktreeList(rootDir, flags.json);
         return;
     }
     if (command === 'create') {
-        await createWorktree({ rootDir }, rest[0]);
+        await createWorktree({ rootDir, flags }, rest[0]);
         return;
     }
     if (command === 'delete') {
-        await deleteWorktree({ rootDir });
+        await deleteWorktree({ rootDir, flags }, rest);
         return;
     }
     if (command === 'open') {
@@ -329,7 +391,7 @@ async function main() {
     }
     const directBranch = rest[0];
     const action = await getUserAction(directBranch);
-    const ctx = { rootDir };
+    const ctx = { rootDir, flags };
     if (action === 'create') {
         await createWorktree(ctx, directBranch);
     }
@@ -374,21 +436,28 @@ async function getUserAction(directBranch) {
     return action;
 }
 async function createWorktree(ctx, directBranch) {
-    const { rootDir } = ctx;
+    const { rootDir, flags } = ctx;
     const defaultBranch = git(rootDir, ['symbolic-ref', '--short', 'refs/remotes/origin/HEAD']).stdout
         .replace(/^origin\//, '')
         .trim() || 'master';
     const { sourceType, selection } = await selectSource(rootDir, directBranch, defaultBranch);
-    const { targetBranch, baseRef, isNewBranch } = await resolveBranchInfo(rootDir, sourceType, selection, directBranch, defaultBranch);
-    const { targetDir, dirName } = await selectTargetDir(rootDir, targetBranch);
-    console.info(chalk.green(`\n准备创建 Worktree:`));
-    console.info(`  分支: ${targetBranch}`);
-    console.info(`  目录: ${targetDir}`);
-    console.info(`  来源: ${baseRef || 'Existing Local'}`);
+    const { targetBranch, baseRef, isNewBranch } = await resolveBranchInfo(rootDir, sourceType, selection, directBranch, defaultBranch, flags);
+    const { targetDir, dirName } = await selectTargetDir(rootDir, targetBranch, flags);
+    if (!flags.json) {
+        console.info(chalk.green(`\n准备创建 Worktree:`));
+        console.info(`  分支: ${targetBranch}`);
+        console.info(`  目录: ${targetDir}`);
+        console.info(`  来源: ${baseRef || 'Existing Local'}`);
+    }
     await createGitWorktree(rootDir, targetDir, targetBranch, baseRef, isNewBranch, sourceType, defaultBranch);
     await setupWorktreeEnv(rootDir, targetDir, dirName);
-    await installDependencies(targetDir);
-    await openInIDE(targetDir);
+    await installDependencies(targetDir, flags.noInstall);
+    await openInIDE(targetDir, flags);
+    if (flags.json) {
+        const items = listWorktrees(rootDir);
+        const created = items.find(x => path.resolve(x.path) === path.resolve(targetDir));
+        console.info(JSON.stringify({ ok: true, data: created || null }));
+    }
 }
 async function selectSource(rootDir, directBranch, defaultBranch) {
     let sourceType;
@@ -430,7 +499,7 @@ async function selectSource(rootDir, directBranch, defaultBranch) {
     }
     return { sourceType, selection };
 }
-async function resolveBranchInfo(rootDir, sourceType, selection, directBranch, defaultBranch) {
+async function resolveBranchInfo(rootDir, sourceType, selection, directBranch, defaultBranch, flags) {
     let targetBranch = '';
     let baseRef = '';
     let isNewBranch = false;
@@ -470,20 +539,26 @@ async function resolveBranchInfo(rootDir, sourceType, selection, directBranch, d
                 isNewBranch = true;
             }
             else {
-                const { createNew } = await inquirer.prompt([
-                    {
-                        type: 'confirm',
-                        name: 'createNew',
-                        message: `分支 ${targetBranch} 不存在。是否基于 ${defaultBranch} 创建新分支?`,
-                        default: true,
-                    },
-                ]);
-                if (createNew) {
-                    baseRef = defaultBranch;
+                if (flags.yes) {
+                    baseRef = flags.base || defaultBranch;
                     isNewBranch = true;
                 }
                 else {
-                    process.exit(1);
+                    const { createNew } = await inquirer.prompt([
+                        {
+                            type: 'confirm',
+                            name: 'createNew',
+                            message: `分支 ${targetBranch} 不存在。是否基于 ${defaultBranch} 创建新分支?`,
+                            default: true,
+                        },
+                    ]);
+                    if (createNew) {
+                        baseRef = defaultBranch;
+                        isNewBranch = true;
+                    }
+                    else {
+                        process.exit(1);
+                    }
                 }
             }
         }
@@ -539,16 +614,26 @@ async function resolveBranchInfo(rootDir, sourceType, selection, directBranch, d
     }
     return { targetBranch, baseRef, isNewBranch };
 }
-async function selectTargetDir(rootDir, targetBranch) {
+async function selectTargetDir(rootDir, targetBranch, flags) {
     const defaultDirName = `worktrees/${targetBranch.split('/').join('-')}`;
-    const { dirName } = await inquirer.prompt([
-        {
-            type: 'input',
-            name: 'dirName',
-            message: `请输入 Worktree 目录路径 (相对于 Git 根目录, 默认: ${defaultDirName}):`,
-            default: defaultDirName,
-        },
-    ]);
+    let dirName;
+    if (flags.dir) {
+        dirName = flags.dir;
+    }
+    else if (flags.yes) {
+        dirName = defaultDirName;
+    }
+    else {
+        const result = await inquirer.prompt([
+            {
+                type: 'input',
+                name: 'dirName',
+                message: `请输入 Worktree 目录路径 (相对于 Git 根目录, 默认: ${defaultDirName}):`,
+                default: defaultDirName,
+            },
+        ]);
+        dirName = result.dirName;
+    }
     const targetDir = path.resolve(rootDir, dirName);
     if (fs.existsSync(targetDir)) {
         console.error(chalk.red(`目录 ${targetDir} 已存在!`));
@@ -594,7 +679,9 @@ async function setupWorktreeEnv(rootDir, targetDir, dirName) {
         }
     }
 }
-async function installDependencies(targetDir) {
+async function installDependencies(targetDir, skip = false) {
+    if (skip)
+        return;
     if (!fs.existsSync(path.join(targetDir, 'package.json')))
         return;
     try {
@@ -615,7 +702,20 @@ function hasCommand(cmd) {
         return false;
     }
 }
-async function openInIDE(targetDir) {
+async function openInIDE(targetDir, flags) {
+    if (flags.noEditor)
+        return;
+    if (flags.editor !== undefined) {
+        if (flags.editor === 'none' || flags.editor === '')
+            return;
+        try {
+            execSync(`${flags.editor} "${targetDir}"`, { stdio: 'ignore' });
+        }
+        catch (e) {
+            void e;
+        }
+        return;
+    }
     const editors = [];
     if (hasCommand('trae'))
         editors.push({ name: `在 Trae 中打开 （trae ${targetDir}）`, value: 'trae' });
@@ -644,34 +744,63 @@ async function openInIDE(targetDir) {
         void e;
     }
 }
-async function deleteWorktree(ctx) {
-    const worktrees = getWorktreeList(ctx.rootDir);
-    const choices = getDeletableWorktrees(ctx.rootDir, worktrees);
+async function deleteWorktree(ctx, targets = []) {
+    const { rootDir, flags } = ctx;
+    const worktrees = getWorktreeList(rootDir);
+    const choices = getDeletableWorktrees(rootDir, worktrees);
     if (choices.length === 0) {
-        console.warn(chalk.yellow('没有可删除的 Worktree (除了主 Worktree)'));
+        if (flags.json) {
+            console.info(JSON.stringify({ ok: true, data: [], message: 'No deletable worktrees' }));
+        }
+        else {
+            console.warn(chalk.yellow('没有可删除的 Worktree (除了主 Worktree)'));
+        }
         return;
     }
-    const { targetPaths } = await inquirer.prompt([
-        {
-            type: 'checkbox',
-            name: 'targetPaths',
-            message: '请选择要删除的 Worktree:',
-            choices,
-            validate: (answer) => (answer.length > 0 ? true : '请至少选择一个'),
-        },
-    ]);
-    const { confirmDelete } = await inquirer.prompt([
-        {
-            type: 'confirm',
-            name: 'confirmDelete',
-            message: `确定要删除这 ${targetPaths.length} 个 Worktree 吗?`,
-            default: false,
-        },
-    ]);
-    if (!confirmDelete)
-        return;
+    let targetPaths;
+    if (targets.length > 0) {
+        // Non-interactive: resolve each target to a worktree path
+        targetPaths = [];
+        for (const key of targets) {
+            const wt = resolveWorktree(rootDir, key);
+            if (!wt) {
+                console.error(chalk.red(`未找到 worktree: ${key}`));
+                process.exit(1);
+            }
+            if (path.resolve(wt.path) === path.resolve(rootDir)) {
+                console.error(chalk.red(`不能删除主 worktree: ${key}`));
+                process.exit(1);
+            }
+            targetPaths.push(wt.path);
+        }
+    }
+    else {
+        // Interactive: checkbox prompt
+        const result = await inquirer.prompt([
+            {
+                type: 'checkbox',
+                name: 'targetPaths',
+                message: '请选择要删除的 Worktree:',
+                choices,
+                validate: (answer) => (answer.length > 0 ? true : '请至少选择一个'),
+            },
+        ]);
+        targetPaths = result.targetPaths;
+    }
+    if (!flags.yes) {
+        const { confirmDelete } = await inquirer.prompt([
+            {
+                type: 'confirm',
+                name: 'confirmDelete',
+                message: `确定要删除这 ${targetPaths.length} 个 Worktree 吗?`,
+                default: false,
+            },
+        ]);
+        if (!confirmDelete)
+            return;
+    }
     for (const targetPath of targetPaths) {
-        await deleteSingleWorktree(ctx.rootDir, targetPath);
+        await deleteSingleWorktree(rootDir, targetPath, flags);
     }
 }
 function getWorktreeList(rootDir) {
@@ -690,29 +819,55 @@ function getDeletableWorktrees(rootDir, worktrees) {
         return { name: `${wt.branch || 'HEAD'} (${relativePath})`, value: wt.path };
     });
 }
-async function deleteSingleWorktree(rootDir, targetPath) {
+async function deleteSingleWorktree(rootDir, targetPath, flags) {
     try {
         gitOrThrow(rootDir, ['worktree', 'remove', targetPath], 'WORKTREE_REMOVE');
-        console.info(chalk.green(`成功删除: ${targetPath}`));
+        if (flags.json) {
+            console.info(JSON.stringify({ ok: true, removed: targetPath }));
+        }
+        else {
+            console.info(chalk.green(`成功删除: ${targetPath}`));
+        }
     }
     catch (e) {
-        console.error(chalk.red(`删除失败: ${errMsg(e)}`));
-        const { force } = await inquirer.prompt([
-            {
-                type: 'confirm',
-                name: 'force',
-                message: '删除失败 (可能有未提交的更改). 强制删除吗?',
-                default: false,
-            },
-        ]);
-        if (!force)
-            return;
-        try {
-            gitOrThrow(rootDir, ['worktree', 'remove', '--force', targetPath], 'WORKTREE_REMOVE_FORCE');
-            console.info(chalk.green(`成功强制删除: ${targetPath}`));
+        if (flags.force) {
+            try {
+                gitOrThrow(rootDir, ['worktree', 'remove', '--force', targetPath], 'WORKTREE_REMOVE_FORCE');
+                if (flags.json) {
+                    console.info(JSON.stringify({ ok: true, removed: targetPath, forced: true }));
+                }
+                else {
+                    console.info(chalk.green(`成功强制删除: ${targetPath}`));
+                }
+            }
+            catch (forceErr) {
+                if (flags.json) {
+                    console.error(JSON.stringify({ ok: false, error: errMsg(forceErr), path: targetPath }));
+                }
+                else {
+                    console.error(chalk.red(`强制删除也失败了: ${errMsg(forceErr)}`));
+                }
+            }
         }
-        catch (forceErr) {
-            console.error(chalk.red(`强制删除也失败了: ${errMsg(forceErr)}`));
+        else {
+            console.error(chalk.red(`删除失败: ${errMsg(e)}`));
+            const { force } = await inquirer.prompt([
+                {
+                    type: 'confirm',
+                    name: 'force',
+                    message: '删除失败 (可能有未提交的更改). 强制删除吗?',
+                    default: false,
+                },
+            ]);
+            if (!force)
+                return;
+            try {
+                gitOrThrow(rootDir, ['worktree', 'remove', '--force', targetPath], 'WORKTREE_REMOVE_FORCE');
+                console.info(chalk.green(`成功强制删除: ${targetPath}`));
+            }
+            catch (forceErr) {
+                console.error(chalk.red(`强制删除也失败了: ${errMsg(forceErr)}`));
+            }
         }
     }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fatdoge/wtree",
   "private": false,
-  "version": "0.1.10",
+  "version": "0.2.0",
   "description": "CLI + UI tool for managing git worktrees",
   "keywords": [
     "git",
@@ -30,6 +30,7 @@
     "api",
     "src",
     "shared",
+    "skills",
     "index.html",
     "vite.config.ts",
     "tailwind.config.js",
@@ -37,6 +38,19 @@
     "README.md",
     "LICENSE"
   ],
+  "scripts": {
+    "client:dev": "vite",
+    "build:ui": "vite build",
+    "build:cli": "tsc -p tsconfig.node.json",
+    "build": "pnpm run build:cli && pnpm run build:ui",
+    "lint": "eslint .",
+    "preview": "vite preview",
+    "check": "tsc --noEmit && tsc -p tsconfig.node.json --noEmit",
+    "server:dev": "nodemon",
+    "dev": "concurrently \"pnpm run client:dev\" \"pnpm run server:dev\"",
+    "wtree": "tsx api/cli/wtree.ts",
+    "test": "vitest run"
+  },
   "dependencies": {
     "@vitejs/plugin-react": "^4.4.1",
     "autoprefixer": "^10.4.21",
@@ -82,18 +96,5 @@
     "typescript": "~5.8.3",
     "typescript-eslint": "^8.30.1",
     "vitest": "^2.1.9"
-  },
-  "scripts": {
-    "client:dev": "vite",
-    "build:ui": "vite build",
-    "build:cli": "tsc -p tsconfig.node.json",
-    "build": "pnpm run build:cli && pnpm run build:ui",
-    "lint": "eslint .",
-    "preview": "vite preview",
-    "check": "tsc --noEmit && tsc -p tsconfig.node.json --noEmit",
-    "server:dev": "nodemon",
-    "dev": "concurrently \"pnpm run client:dev\" \"pnpm run server:dev\"",
-    "wtree": "tsx api/cli/wtree.ts",
-    "test": "vitest run"
   }
-}
+}

package/skills/wtree/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: wtree
+description: "Manage git worktrees using the wtree CLI. Use when the user wants to create, list, delete, open, lock, unlock, or prune git worktrees, or work with multiple branches simultaneously."
+allowed-tools: Bash
+user-invocable: true
+---
+
+# wtree - Git Worktree Manager
+
+You manage git worktrees using the `wtree` CLI tool. Always use non-interactive flags so commands complete without user input.
+
+## Prerequisites
+
+The `wtree` CLI must be installed globally (`npm install -g @fatdoge/wtree`) or run via `npx @fatdoge/wtree`. If working inside the wtree project itself, use `node dist-node/api/cli/wtree.js`.
+
+## Important Rules
+
+1. **Always use `--json` flag** when you need to parse output programmatically
+2. **Always use `--yes`** to skip all confirmation prompts
+3. **Always use `--no-editor`** unless the user explicitly asks to open an editor
+4. **Always use `--no-install`** unless the user explicitly asks to install dependencies
+5. **Use `--repo <path>`** if the current working directory is not inside the target git repository
+6. **Never run `wtree` without a subcommand** — that enters interactive mode
+
+## Commands Reference
+
+### List Worktrees
+
+```bash
+wtree list --json
+# With specific repo:
+wtree list --json --repo /path/to/repo
+```
+
+Returns a JSON array of worktree objects:
+```json
+[
+  {
+    "id": "<base64url-encoded-path>",
+    "path": "/absolute/path/to/worktree",
+    "head": "<commit-sha>",
+    "branch": "branch-name",
+    "isMain": true,
+    "isLocked": false
+  }
+]
+```
+
+### Create Worktree
+
+For an **existing** local or remote branch:
+```bash
+wtree create <branch-name> --yes --no-editor --no-install --json
+```
+
+For a **new branch** based on a reference:
+```bash
+wtree create <new-branch-name> --base <base-ref> --yes --no-editor --no-install --json
+```
+
+With a specific target directory:
+```bash
+wtree create <branch> --dir <relative-path> --yes --no-editor --no-install --json
+```
+
+Parameters:
+- `<branch-name>` (positional, required): The branch to check out or create
+- `--dir <path>`: Worktree directory, relative to repo root (default: `worktrees/<branch-sanitized>`)
+- `--base <ref>`: Base reference for new branch creation (e.g., `main`, `origin/main`)
+- `--yes`: Auto-confirm new branch creation and accept default directory
+- `--editor <name>`: Open in specific editor after creation (`trae`, `cursor`, `code`)
+- `--no-editor`: Do not open any editor
+- `--no-install`: Skip automatic dependency installation
+- `--json`: Output result as JSON
+
+Returns on success:
+```json
+{"ok": true, "data": {"id": "...", "path": "...", "head": "...", "branch": "...", "isMain": false, "isLocked": false}}
+```
+
+### Delete Worktree
+
+Delete one or more worktrees by branch name or path:
+```bash
+wtree delete <branch-or-path> --yes --json
+wtree delete <branch1> <branch2> --yes --json
+```
+
+Force delete (even with uncommitted changes):
+```bash
+wtree delete <branch> --yes --force --json
+```
+
+Parameters:
+- Positional args: Worktree identifiers (branch name, path, or directory basename)
+- `--yes`: Skip deletion confirmation
+- `--force`: Force-delete even if there are uncommitted changes
+- `--json`: Output result as JSON
+
+### Open Worktree
+
+```bash
+wtree open <branch-or-path>
+```
+
+Opens the worktree directory in the system file manager.
+
+### Lock / Unlock Worktree
+
+```bash
+wtree lock <branch-or-path>
+wtree unlock <branch-or-path>
+```
+
+### Prune Invalid Worktrees
+
+```bash
+wtree prune
+```
+
+Removes worktree records for directories that no longer exist.
+
+### Configuration
+
+```bash
+wtree config                       # Show all config as JSON
+wtree config get <key>            # Get a single config value
+wtree config set <key> <value>    # Set a config value
+```
+
+Available config keys: `baseDir`, `openCommand`, `editorCommand`
+
+## Workflow Examples
+
+### Create a worktree for a new feature branch
+
+```bash
+# 1. List existing worktrees
+wtree list --json
+
+# 2. Create worktree with new branch from main
+wtree create feature/my-feature --base main --yes --no-editor --no-install --json
+```
+
+### Clean up old worktrees
+
+```bash
+# 1. List all worktrees
+wtree list --json
+
+# 2. Delete unwanted ones
+wtree delete feature/old-branch --yes --json
+
+# 3. Prune stale records
+wtree prune
+```
+
+### Create worktree for an existing remote branch
+
+```bash
+wtree create feature/existing-branch --yes --no-editor --no-install --json
+```