@junheep/gwt 0.1.1 → 0.2.1

package/README.md

@@ -33,6 +33,38 @@ confirmation. The integration also provides Zsh completion for commands,
 options, worktrees, and Git refs. It only changes directories; it does not load
 environment variables or run project hooks.
 
+## Coding agents
+
+Coding agents do not know about `gwt` and reach for `git worktree add`, which
+skips the copied files, assigned ports, and setup hooks. Install a skill that
+tells them otherwise:
+
+```sh
+gwt skill install claude
+gwt skill install codex
+```
+
+The installer shows the target path and asks for confirmation before writing.
+Both agents read the same `SKILL.md` format and differ only in location, so
+the installed skill is identical:
+
+| Agent  | Default                        | With `--project`             |
+| ------ | ------------------------------ | ---------------------------- |
+| Claude | `~/.claude/skills/gwt/SKILL.md` | `.claude/skills/gwt/SKILL.md` |
+| Codex  | `~/.agents/skills/gwt/SKILL.md` | `.agents/skills/gwt/SKILL.md` |
+
+`--project` writes into the primary worktree so the skill can be committed for
+the team.
+
+The skill covers what `gwt --help` does not: that gwt is preferred over native
+`git worktree`, that project hooks need `gwt trust`, that a failed setup is
+retried rather than recreated, that ports come from `gwt info`, and that
+removal is destructive. It points at `gwt <command> --help` for command
+details instead of repeating them, so it does not go stale as gwt changes.
+Reinstall after upgrading to pick up a revised skill; an unchanged file is
+reported as already installed, and a modified one is replaced only after
+confirmation.
+
 ## Configuration
 
 Create user configuration for the current repository:
@@ -167,6 +199,7 @@ gwt trust [--revoke]
 gwt config create [--project]
 gwt config show
 gwt shell install zsh [--dry-run] [--yes]
+gwt skill install <claude|codex> [--project] [--dry-run] [--yes]
 ```
 
 Run `gwt --help` for the command overview, or `gwt <command> --help` for
@@ -181,9 +214,9 @@ Setup failures retain the worktree and record the failure. Retry with
 `gwt setup <id>` or remove it explicitly.
 
 Run `gwt switch` without a target to open the interactive picker. Use the
-arrow keys, `j`/`k`, or Ctrl-n/Ctrl-p to move; press 1–9 to select a numbered
-row immediately; or press `/` to filter by branch, ID, or path. Enter switches
-to the selected worktree. Escape leaves filter mode or cancels the picker.
+arrow keys, `j`/`k`, or Ctrl-n/Ctrl-p to move; press `/` to filter by branch,
+ID, or path. Enter switches to the selected worktree. Escape leaves filter
+mode or cancels the picker.
 
 `gwt remove` refuses dirty worktrees and first tries to delete the branch with
 `git branch -d`. If Git rejects safe deletion, an interactive terminal asks

package/bin/gwt.mjs

@@ -23,12 +23,14 @@ import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path"
 import { emitKeypressEvents } from "node:readline"
 import { createInterface } from "node:readline/promises"
 
-const VERSION = "0.1.0"
 const PROJECT_CONFIG_FILE = ".gwt.json"
 const PORT_MIN = 20_000
 const PORT_MAX = 39_999
+const PICKER_ESCAPE_CODE_TIMEOUT_MS = 50
 const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/
 const DEFAULT_CONFIG = { worktreeDirectory: ".worktrees", copyFiles: [], ports: [] }
+const SKILL_DIRECTORIES = { claude: ".claude", codex: ".agents" }
+const SKILL_USAGE = `Usage: gwt skill install <${Object.keys(SKILL_DIRECTORIES).join("|")}> [--project] [--dry-run] [--yes]`
 
 class CliError extends Error {}
 
@@ -654,17 +656,35 @@ async function commandNew(args) {
   }
 }
 
-async function chooseWorktree(repository) {
-  if (!process.stdin.isTTY || !process.stdout.isTTY) throw new CliError("A worktree selector is required in non-interactive mode")
+function linkedWorktreeRows(repository, metadata = loadMetadata(repository)) {
   const current = currentWorktree(repository)
-  const choices = repository.worktrees.map((worktree, index) => {
-    const metadata = metadataForWorktree(repository, worktree)
-    const relativePath = relative(repository.primaryPath, worktree.path)
+  return repository.worktrees.map((worktree, index) => {
+    const item = metadata.find((entry) => resolve(entry.path) === resolve(worktree.path))
     return {
       worktree,
-      current: resolve(current?.path ?? "") === resolve(worktree.path),
+      current: current && resolve(current.path) === resolve(worktree.path),
+      id: item?.id ?? (index === 0 ? "primary" : "-"),
       branch: worktree.branch ?? "(detached)",
-      id: metadata?.id ?? (index === 0 ? "primary" : "native"),
+      setup: item?.setup ?? (index === 0 ? "-" : "unmanaged"),
+      path: worktree.path,
+    }
+  })
+}
+
+function terminalColors() {
+  if (!process.stdout.isTTY || process.env.NO_COLOR !== undefined) {
+    return { cyan: "", yellow: "", dim: "", reset: "" }
+  }
+  return { cyan: "\x1b[36m", yellow: "\x1b[33m", dim: "\x1b[2m", reset: "\x1b[0m" }
+}
+
+async function chooseWorktree(repository) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) throw new CliError("A worktree selector is required in non-interactive mode")
+  const choices = linkedWorktreeRows(repository).map((row) => {
+    const { worktree } = row
+    const relativePath = relative(repository.primaryPath, worktree.path)
+    return {
+      ...row,
       path: relativePath === "" ? "." : relativePath.startsWith(`..${sep}`) ? worktree.path : relativePath,
     }
   })
@@ -672,12 +692,11 @@ async function chooseWorktree(repository) {
   return new Promise((resolveChoice, rejectChoice) => {
     let query = ""
     let filtering = false
-    let selected = Math.max(0, choices.findIndex((choice) => choice.current))
+    const initialSelected = Math.max(0, choices.findIndex((choice) => choice.current))
+    let selected = initialSelected
     let renderedLines = 0
     const wasRaw = process.stdin.isRaw
-    const colors = process.env.NO_COLOR === undefined
-      ? { cyan: "\x1b[36m", yellow: "\x1b[33m", dim: "\x1b[2m", reset: "\x1b[0m" }
-      : { cyan: "", yellow: "", dim: "", reset: "" }
+    const colors = terminalColors()
 
     const clear = () => {
       if (renderedLines > 0) process.stdout.write(`\x1b[${renderedLines}A\r\x1b[J`)
@@ -690,22 +709,24 @@ async function chooseWorktree(repository) {
         .some((value) => value.toLowerCase().includes(normalizedQuery)))
       if (selected >= filtered.length) selected = Math.max(0, filtered.length - 1)
 
-      const terminalWidth = Math.max(40, process.stdout.columns ?? 100)
-      const numberWidth = String(Math.max(1, filtered.length)).length
+      const terminalWidth = Math.max(48, process.stdout.columns ?? 100)
       const idWidth = 8
+      const setupWidth = Math.max(5, ...filtered.map((choice) => choice.setup.length))
       const longestBranch = Math.max(12, ...filtered.map((choice) => choice.branch.length))
-      const branchWidth = Math.min(32, longestBranch, terminalWidth - numberWidth - idWidth - 22)
-      const pathWidth = Math.max(8, terminalWidth - numberWidth - branchWidth - idWidth - 10)
+      const flexibleWidth = terminalWidth - idWidth - setupWidth - 10
+      const branchWidth = Math.min(32, longestBranch, Math.max(8, flexibleWidth - 8))
+      const pathWidth = Math.max(8, flexibleWidth - branchWidth)
       const fit = (value, width) => value.length > width
         ? `${value.slice(0, Math.max(0, width - 1))}…`
         : value.padEnd(width)
       const visibleCount = Math.max(3, (process.stdout.rows ?? 24) - 5)
       const start = Math.max(0, Math.min(selected - Math.floor(visibleCount / 2), filtered.length - visibleCount))
       const visible = filtered.slice(start, start + visibleCount)
+      const escapeAction = filtering ? "clear" : "cancel"
       const lines = [
-        `${colors.dim}${fit("Switch worktree  ↑↓/jk/C-n/C-p move · 1-9 select · / filter · Enter", terminalWidth)}${colors.reset}`,
-        fit(`Filter: ${filtering ? "/" : ""}${query}`, terminalWidth),
-        `${colors.dim}  ${fit("#", numberWidth)}    ${fit("BRANCH", branchWidth)}  ${fit("ID", idWidth)}  ${fit("PATH", pathWidth)}${colors.reset}`,
+        `${colors.dim}${fit(`Switch worktree  Esc ${escapeAction} · Enter select · ↑↓/jk/C-n/C-p · / filter`, terminalWidth)}${colors.reset}`,
+        ...(filtering ? [fit(`Filter: /${query}`, terminalWidth)] : []),
+        `${colors.dim}    ${fit("BRANCH", branchWidth)}  ${fit("ID", idWidth)}  ${fit("SETUP", setupWidth)}  ${fit("PATH", pathWidth)}${colors.reset}`,
       ]
 
       if (visible.length === 0) {
@@ -714,8 +735,8 @@ async function chooseWorktree(repository) {
         visible.forEach((choice, visibleIndex) => {
           const index = start + visibleIndex
           const selection = index === selected ? `${colors.cyan}>${colors.reset}` : " "
-          const currentMarker = choice.current ? `${colors.yellow}@${colors.reset}` : " "
-          lines.push(`${selection} ${fit(String(index + 1), numberWidth)}  ${currentMarker} ${fit(choice.branch, branchWidth)}  ${fit(choice.id, idWidth)}  ${fit(choice.path, pathWidth)}`)
+          const currentMarker = choice.current ? `${colors.yellow}*${colors.reset}` : " "
+          lines.push(`${selection} ${currentMarker} ${fit(choice.branch, branchWidth)}  ${fit(choice.id, idWidth)}  ${fit(choice.setup, setupWidth)}  ${fit(choice.path, pathWidth)}`)
         })
       }
 
@@ -746,7 +767,10 @@ async function chooseWorktree(repository) {
       }
       if (key.name === "escape") {
         if (filtering) {
+          const selectedChoice = filtered[selected]
           filtering = false
+          query = ""
+          selected = selectedChoice ? choices.indexOf(selectedChoice) : initialSelected
           render()
         } else {
           finish(new CliError("Selection cancelled"))
@@ -767,11 +791,6 @@ async function chooseWorktree(repository) {
       } else if (filtering && key.name === "backspace") {
         query = [...query].slice(0, -1).join("")
         selected = 0
-      } else if (!filtering && /^[1-9]$/.test(text)) {
-        const choice = filtered[Number(text) - 1]
-        if (choice) finish(null, choice)
-        else process.stdout.write("\x07")
-        return
       } else if (filtering && text && !key.ctrl && !key.meta) {
         query += text.replace(/[\x00-\x1f\x7f]/g, "")
         selected = 0
@@ -779,7 +798,7 @@ async function chooseWorktree(repository) {
       render()
     }
 
-    emitKeypressEvents(process.stdin)
+    emitKeypressEvents(process.stdin, { escapeCodeTimeout: PICKER_ESCAPE_CODE_TIMEOUT_MS })
     process.stdin.on("keypress", onKeypress)
     process.stdout.on("resize", render)
     process.stdin.setRawMode(true)
@@ -798,18 +817,8 @@ async function commandSwitch(args) {
 }
 
 function worktreeRows(repository) {
-  const current = currentWorktree(repository)
   const metadata = loadMetadata(repository)
-  const rows = repository.worktrees.map((worktree, index) => {
-    const item = metadata.find((entry) => resolve(entry.path) === resolve(worktree.path))
-    return {
-      current: current && resolve(current.path) === resolve(worktree.path),
-      id: item?.id ?? (index === 0 ? "primary" : "-"),
-      branch: worktree.branch ?? "(detached)",
-      setup: item?.setup ?? (index === 0 ? "-" : "unmanaged"),
-      path: worktree.path,
-    }
-  })
+  const rows = linkedWorktreeRows(repository, metadata)
   const registeredPaths = new Set(repository.worktrees.map((worktree) => resolve(worktree.path)))
   for (const item of metadata.filter((entry) => !registeredPaths.has(resolve(entry.path)))) {
     rows.push({ current: false, id: item.id, branch: "-", setup: "stale", path: item.path })
@@ -849,14 +858,16 @@ function commandList(args) {
   if (args.length > 0) throw new CliError("Usage: gwt list")
   const repository = discoverRepository()
   const rows = worktreeRows(repository)
+  const colors = terminalColors()
   const widths = {
-    id: Math.max(2, ...rows.map((row) => displayWidth(row.id))),
     branch: Math.max(6, ...rows.map((row) => displayWidth(row.branch))),
+    id: Math.max(2, ...rows.map((row) => displayWidth(row.id))),
     setup: Math.max(5, ...rows.map((row) => displayWidth(row.setup))),
   }
-  console.log(`  ${padDisplay("ID", widths.id)}  ${padDisplay("BRANCH", widths.branch)}  ${padDisplay("SETUP", widths.setup)}  PATH`)
+  console.log(`${colors.dim}  ${padDisplay("BRANCH", widths.branch)}  ${padDisplay("ID", widths.id)}  ${padDisplay("SETUP", widths.setup)}  PATH${colors.reset}`)
   for (const row of rows) {
-    console.log(`${row.current ? "*" : " "} ${padDisplay(row.id, widths.id)}  ${padDisplay(row.branch, widths.branch)}  ${padDisplay(row.setup, widths.setup)}  ${row.path}`)
+    const currentMarker = row.current ? `${colors.yellow}*${colors.reset}` : " "
+    console.log(`${currentMarker} ${padDisplay(row.branch, widths.branch)}  ${padDisplay(row.id, widths.id)}  ${padDisplay(row.setup, widths.setup)}  ${row.path}`)
   }
 }
 
@@ -1076,6 +1087,7 @@ if command -v gwt >/dev/null 2>&1; then
       'trust:Approve project hooks'
       'config:Manage user and project configuration'
       'shell:Install shell integration'
+      'skill:Install the gwt skill for coding agents'
     )
 
     if (( CURRENT == 2 )); then
@@ -1133,6 +1145,15 @@ if command -v gwt >/dev/null 2>&1; then
           '--yes[skip installation confirmation]' \
           '(-h --help)'{-h,--help}'[show help]'
         ;;
+      skill)
+        _arguments \
+          '2:action:(install)' \
+          '3:agent:(claude codex)' \
+          '--project[install into the repository instead of the home directory]' \
+          '--dry-run[show the change without writing]' \
+          '--yes[skip installation confirmation]' \
+          '(-h --help)'{-h,--help}'[show help]'
+        ;;
     esac
   }
 
@@ -1142,6 +1163,92 @@ if command -v gwt >/dev/null 2>&1; then
 fi`
 }
 
+function agentSkill() {
+  return `---
+name: gwt
+description: Use gwt to create, list, switch, and remove Git worktrees. Use whenever a task needs an isolated worktree, or in place of running 'git worktree' directly.
+---
+
+gwt wraps native Git worktrees and prepares each one with the project's local
+files, assigned ports, and setup hooks.
+
+## Prefer gwt over 'git worktree'
+
+Create worktrees with \`gwt new\`, not \`git worktree add\`. A worktree added with
+plain Git skips the configured file copies, port assignment, and postCreate
+hook, and records no gwt metadata, so \`gwt list\` and \`gwt remove\` cannot manage
+it. Adopt an existing one with \`gwt setup <path>\`.
+
+## Read the help instead of guessing flags
+
+\`gwt --help\` lists the commands, \`gwt <command> --help\` documents arguments,
+options, and behavior, and nested commands such as \`gwt config create --help\`
+have their own help. This skill does not repeat command signatures so that they
+stay accurate across versions.
+
+## What the help does not make obvious
+
+- Hooks declared by a committed \`.gwt.json\` do not run until the repository is
+  approved with \`gwt trust\`. Approval is invalidated whenever the config or a
+  hook changes, so a repository that worked before can start asking again.
+- A failed setup keeps the worktree and records the failure. Retry it with
+  \`gwt setup <id>\` rather than removing and recreating the worktree.
+- Ports are assigned per worktree. Read them from \`gwt info\` instead of assuming
+  a project default; two worktrees of the same project never share a port.
+- \`gwt switch\` changes the shell's directory only when the shell integration is
+  installed. Otherwise it just prints the path.
+- \`gwt switch\` with no target opens an interactive picker, so always pass an
+  explicit target when running non-interactively.
+
+## Removal is destructive
+
+\`gwt remove\` deletes the worktree and, by default, its branch. Confirm with the
+user before running it, and never pass \`--discard --yes\` on your own: together
+they discard uncommitted changes and force-delete an unmerged branch.
+`
+}
+
+function skillPath(agent, project) {
+  const base = project ? discoverRepository().primaryPath : homedir()
+  return join(base, SKILL_DIRECTORIES[agent], "skills", "gwt", "SKILL.md")
+}
+
+async function installSkill(agent, args) {
+  const { options, positionals } = parseOptions(args, {
+    "--project": "boolean",
+    "--dry-run": "boolean",
+    "--yes": "boolean",
+  })
+  if (positionals.length > 0) throw new CliError(SKILL_USAGE)
+
+  const path = skillPath(agent, options.project)
+  const contents = agentSkill()
+  const existing = existsSync(path) ? readFileSync(path, "utf8") : null
+  if (existing === contents) {
+    console.log(`Skill is already installed in ${path}`)
+    return
+  }
+
+  const verb = existing === null ? "Create" : "Replace"
+  console.log(`${verb} ${path}`)
+  if (options["dry-run"]) {
+    console.log(`\n${contents}`)
+    return
+  }
+  if (!options.yes && !(await ask(`${verb}? [y/N] `))) throw new CliError("Skill installation cancelled")
+
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path, contents)
+  console.log(`Installed skill in ${path}`)
+}
+
+async function commandSkill(args) {
+  if (args[0] === "install" && Object.hasOwn(SKILL_DIRECTORIES, args[1])) {
+    return installSkill(args[1], args.slice(2))
+  }
+  throw new CliError(SKILL_USAGE)
+}
+
 function zshConfigPath() {
   return join(process.env.ZDOTDIR ? resolve(process.env.ZDOTDIR) : homedir(), ".zshrc")
 }
@@ -1211,10 +1318,15 @@ function commandComplete(args) {
   throw new CliError("Invalid completion request")
 }
 
+function version() {
+  const path = join(import.meta.dirname, "..", "package.json")
+  return JSON.parse(readFileSync(path, "utf8")).version
+}
+
 function help(command, subcommand) {
   const topic = [command, subcommand].filter(Boolean).join(" ")
   const texts = {
-    "": `gwt ${VERSION} - lightweight native Git worktree workflows
+    "": `gwt ${version()} - lightweight native Git worktree workflows
 
 Usage:
   gwt <command> [options]
@@ -1229,6 +1341,7 @@ Commands:
   trust     Approve or revoke repository project hooks
   config    Create or inspect configuration
   shell     Install shell integration
+  skill     Install the gwt skill for coding agents
 
 Options:
   -h, --help      Show help.
@@ -1240,6 +1353,7 @@ Examples:
   gwt remove
   gwt config create
   gwt shell install zsh
+  gwt skill install claude
 
 Run 'gwt <command> --help' for command behavior and more examples.`,
     new: `Create a worktree, prepare its development environment, and switch to it.
@@ -1313,9 +1427,9 @@ Options:
   -h, --help      Show help for this command.
 
 Behavior:
-  The picker supports arrow keys, j/k, Ctrl-n/Ctrl-p, number shortcuts, and
-  '/' filtering. Shell integration must be installed for gwt to change the
-  parent shell's directory; otherwise the selected path is only printed.
+  The picker supports arrow keys, j/k, Ctrl-n/Ctrl-p, and '/' filtering. Shell
+  integration must be installed for gwt to change the parent shell's directory;
+  otherwise the selected path is only printed.
 
 Examples:
   gwt switch
@@ -1460,6 +1574,50 @@ when ZDOTDIR is set. Restart Zsh or source the file after installation.
 Examples:
   gwt shell install zsh
   gwt shell install zsh --dry-run`,
+    skill: `Install the gwt skill so coding agents use gwt correctly.
+
+Usage:
+  gwt skill install <claude|codex> [--project] [--dry-run] [--yes]
+
+Options:
+  -h, --help      Show help for this command.
+
+The skill teaches an agent to prefer gwt over native 'git worktree', to read
+'gwt <command> --help' for command details, and to treat removal as
+destructive. It does not duplicate command signatures, so it stays accurate
+as gwt changes.
+
+Examples:
+  gwt skill install claude
+  gwt skill install codex`,
+    "skill install": `Install the gwt skill for a coding agent.
+
+Usage:
+  gwt skill install <claude|codex> [--project] [--dry-run] [--yes]
+
+Arguments:
+  claude          Install for Claude Code, under .claude/skills.
+  codex           Install for Codex, under .agents/skills.
+
+Options:
+  --project       Write the skill inside the primary worktree, so it can be
+                  committed for the team, instead of the home directory.
+  --dry-run       Print the target path and the skill without writing it.
+  --yes           Install without asking for confirmation.
+  -h, --help      Show help for this command.
+
+Both agents read the same SKILL.md format and only differ in location, so the
+installed skill is identical. Install it once per agent.
+
+Reinstall after upgrading gwt to pick up a revised skill. The command reports
+an unchanged file as already installed and asks before replacing a modified
+one.
+
+Examples:
+  gwt skill install claude
+  gwt skill install codex
+  gwt skill install codex --project
+  gwt skill install claude --dry-run`,
   }
 
   if (!Object.hasOwn(texts, topic)) throw new CliError(`Unknown help topic: ${topic}`)
@@ -1470,9 +1628,9 @@ async function main() {
   const [command, ...args] = process.argv.slice(2)
   if (!command || command === "--help" || command === "-h") return help()
   if (command === "help") return help(args[0], args[1])
-  if (command === "--version" || command === "-V") return console.log(VERSION)
+  if (command === "--version" || command === "-V") return console.log(version())
   if (args.includes("--help") || args.includes("-h")) {
-    const subcommand = ["config", "shell"].includes(command)
+    const subcommand = ["config", "shell", "skill"].includes(command)
       ? args.find((argument) => !argument.startsWith("-"))
       : undefined
     return help(command, subcommand)
@@ -1486,6 +1644,7 @@ async function main() {
   if (command === "trust") return commandTrust(args)
   if (command === "config") return commandConfig(args)
   if (command === "shell") return commandShell(args)
+  if (command === "skill") return commandSkill(args)
   if (command === "__complete") return commandComplete(args)
   throw new CliError(`Unknown command: ${command}`)
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@junheep/gwt",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Lightweight native Git worktree workflows",
   "license": "MIT",
   "author": "Junhee Park",