Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
refactor(plugin): relocate Gemini extension to repo root (#2807)
Maximilian Roosd7e33efc6c6b
diff --git a/CLAUDE.md b/CLAUDE.mdindex 2d3de616e..1f565781f 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -170,13 +170,13 @@ Config docs (`USER_CONFIG_START`/`PROJECT_CONFIG_START` sections in `src/cli/mod## Plugin Layout-One plugin payload serves both tools, in `plugins/worktrunk/`. The repo root keeps only the two loader-mandated marketplace pointers — Claude (`.claude-plugin/marketplace.json`) and Codex (`.agents/plugins/marketplace.json`) each hardcode their marketplace path with no fallback, so two pointer files is the irreducible floor. Both point `source` at `./plugins/worktrunk`. Inside that directory: `plugin.json` is the Claude manifest (at the plugin root — Claude's `.claude-plugin/` wrapper is marketplace-root-only), `.codex-plugin/plugin.json` is the Codex manifest (Codex's required wrapper), and `skills -> ../../skills` single-sources the skills across both plugins and the docs auto-sync. The full layout, path-resolution rules, and the live-CLI verification are documented in `plugins/worktrunk/CLAUDE.md`; keep that file current when the layout changes.+Claude Code and Codex share one payload dir, `plugins/worktrunk/`; Gemini resolves its extension at the repo root itself. Each tool hardcodes its loader path with no fallback, so the repo root carries one pointer per tool: Claude's `.claude-plugin/marketplace.json` and Codex's `.agents/plugins/marketplace.json` (both `source → ./plugins/worktrunk`), and Gemini's `gemini-extension.json` plus `hooks/hooks.json` (Gemini hard-probes `${extensionPath}/{hooks,skills}/` at the extension root, which is the repo root). Inside `plugins/worktrunk/`: `plugin.json` is the Claude manifest (at the plugin root — Claude's `.claude-plugin/` wrapper is marketplace-root-only) and `.codex-plugin/plugin.json` is the Codex manifest (Codex's required wrapper). The repo-root `skills/` is the single source — Claude/Codex reach it via `plugins/worktrunk/skills -> ../../skills`, Gemini via `${extensionPath}/skills` (the root) — and it feeds the docs auto-sync. The full layout, path-resolution rules, and live-CLI verification are documented in `plugins/worktrunk/CLAUDE.md`; keep that file current when the layout changes.-**Gemini extension — `plugins/gemini/`.** Gemini CLI gets its own sibling payload dir (it can't share `plugins/worktrunk/`, whose `hooks/hooks.json` slot is Claude's). It holds `gemini-extension.json`, `hooks/hooks.json`, a `skills -> ../../skills` symlink, and a **bundled `hooks/wt.sh`** — byte-identical to `plugins/worktrunk/hooks/wt.sh`, drift-guarded by `test_plugin_layout_is_consolidated` — because `gemini extensions install` *copies* the extension dir, so a cross-dir reference to the shared shim would break in the copy. Two constraints follow from that copy behaviour and Gemini reading `gemini-extension.json` only at the source root: (1) **github-URL install is unsupported** (`gemini extensions install owner/repo` reads `<clone-root>/gemini-extension.json`, absent with the manifest under `plugins/gemini/`) — install via a local path until a `wt config plugins gemini install` command exists; (2) Gemini's `fs.cp` rewrites the relative `skills` symlink to an **absolute path**, so a local install works only while the source repo stays in place, and a git/URL install would lose the skills entirely (tempdir target deleted → silently empty). The robust fix — bundling copied SKILL.md trees at release time, drift-guarded like `wt.sh` — is tracked with the `wt config plugins gemini install` follow-up.+**Gemini extension — repo root.** Gemini hard-probes `${extensionPath}/hooks/hooks.json` and `${extensionPath}/skills/` with no manifest path indirection, and `gemini extensions install owner/repo` reads `gemini-extension.json` only at the clone root. So Gemini's manifest is itself a loader-mandated root pointer (the third tool pointer), `hooks/hooks.json` sits at the repo root, and `${extensionPath}/skills/` resolves to the real single-sourced repo-root `skills/`. The hooks call the canonical `${extensionPath}/plugins/worktrunk/hooks/wt.sh` by its real path — no symlink, no bundled copy, no drift guard. Native `gemini extensions install owner/repo` works (`gemini extensions validate .` is the non-interactive check). This replaced an earlier `plugins/gemini/` sibling dir whose `skills` symlink and bundled `wt.sh` existed only to survive `gemini extensions install`'s `fs.cp`, and which broke github-URL install entirely; relocating to the root deletes all of that. `test_plugin_layout_is_consolidated` guards the layout.**No Codex activity-marker hooks.** The Claude manifest carries `hooks: "./hooks/hooks.json"`; the Codex manifest has no `hooks` key and Codex ships no hooks. Codex's `HookEventNameWire` vocabulary (codex-cli 0.130.0: `PreToolUse`, `PermissionRequest`, `PostToolUse`, `PreCompact`, `PostCompact`, `SessionStart`, `UserPromptSubmit`) has no `Stop`/turn-end event, so a 🤖 marker set on `UserPromptSubmit` could never return to 💬 — it would stick at "working" indefinitely. Re-add a Codex `hooks.json`, the `hooks` manifest key, the install hints in `src/commands/config/codex.rs`, and the docs (`docs/content/claude-code.md` "Activity tracking", `src/cli/config.rs` plugin list) once Codex exposes a turn-end hook event.-**Accepted tradeoff — `skills` exposes `wt-switch-create` to Codex.** The Codex manifest's `"skills": "./skills/"` resolves through the shared `skills` symlink, exposing the entire repo-root `skills/` directory — including `wt-switch-create`, which depends on Claude session-cwd switching and the `WorktreeCreate` hook that Codex doesn't provide. We accept this: Codex loading a skill it can't act on is harmless, and a single repo-root `skills/` keeps the `worktrunk` skill single-source across both plugins and the docs sync. Don't add a Codex-only skills subtree to exclude it.+**Accepted tradeoff — the shared `skills/` exposes `wt-switch-create` to Codex and Gemini.** Codex's `"skills": "./skills/"` and Gemini's `${extensionPath}/skills/` both resolve the entire repo-root `skills/` directory — including `wt-switch-create`, which depends on Claude session-cwd switching and the `WorktreeCreate` hook neither provides. We accept this: a tool loading a skill it can't act on is harmless, and a single repo-root `skills/` keeps the `worktrunk` skill single-source across all three tools and the docs sync. Don't add per-tool skills subtrees to exclude it.## Data Safetydiff --git a/plugins/gemini/gemini-extension.json b/gemini-extension.jsonsimilarity index 100%rename from plugins/gemini/gemini-extension.jsonrename to gemini-extension.jsondiff --git a/plugins/gemini/hooks/hooks.json b/hooks/hooks.jsonsimilarity index 53%rename from plugins/gemini/hooks/hooks.jsonrename to hooks/hooks.jsonindex c00520f23..794bbb88c 100644--- a/plugins/gemini/hooks/hooks.json+++ b/hooks/hooks.json@@ -5,7 +5,7 @@"hooks": [{"type": "command",- "command": "bash \"${extensionPath}/hooks/wt.sh\" config state marker set 🤖 || true"+ "command": "bash \"${extensionPath}/plugins/worktrunk/hooks/wt.sh\" config state marker set 🤖 || true"}]}@@ -15,7 +15,7 @@"hooks": [{"type": "command",- "command": "bash \"${extensionPath}/hooks/wt.sh\" config state marker set 💬 || true"+ "command": "bash \"${extensionPath}/plugins/worktrunk/hooks/wt.sh\" config state marker set 💬 || true"}]}@@ -25,7 +25,7 @@"hooks": [{"type": "command",- "command": "bash \"${extensionPath}/hooks/wt.sh\" config state marker clear || true"+ "command": "bash \"${extensionPath}/plugins/worktrunk/hooks/wt.sh\" config state marker clear || true"}]}diff --git a/plugins/gemini/hooks/wt.sh b/plugins/gemini/hooks/wt.shdeleted file mode 100755index a7a4a72e1..000000000--- a/plugins/gemini/hooks/wt.sh+++ /dev/null@@ -1,39 +0,0 @@-#!/usr/bin/env bash-# Cross-platform wrapper for the worktrunk CLI.-# If WORKTRUNK_BIN is set, uses that path exclusively.-# Otherwise, on Windows (MSYS/Cygwin), prefers git-wt.exe over wt and-# rejects wt if it resolves to Windows Terminal (.../WindowsApps/wt.exe).-# On other platforms, uses wt directly.-# Usage: wt.sh [args...]--if [[ -n "$WORKTRUNK_BIN" ]]; then- if ! command -v "$WORKTRUNK_BIN" >/dev/null 2>&1; then- echo "worktrunk: WORKTRUNK_BIN is set to '$WORKTRUNK_BIN' but it was not found" >&2- exit 1- fi- WT="$WORKTRUNK_BIN"-elif [[ "$(uname -o 2>/dev/null)" =~ ^(Msys|Cygwin)$ ]]; then- # check for bash on Windows (on Windows, Claude Code defaults to Git Bash)- if command -v git-wt.exe >/dev/null 2>&1; then- # prefer git-wt over wt if available- WT=git-wt.exe- elif command -v wt >/dev/null 2>&1; then- # reject wt if it's the Windows Terminal alias- if [[ "$(command -v wt)" == *WindowsApps* ]]; then- echo "worktrunk: 'wt' resolves to Windows Terminal; install worktrunk as git-wt.exe or remove the Windows Terminal alias. See https://worktrunk.dev/worktrunk/#install" >&2- exit 1- fi-- WT=wt- fi-else- # non-Windows, always use wt- WT=wt-fi--if [[ -z "$WT" ]] || ! command -v "$WT" >/dev/null 2>&1; then- echo "worktrunk: could not find 'wt' in PATH" >&2- exit 1-fi--"$WT" "$@"diff --git a/plugins/gemini/skills b/plugins/gemini/skillsdeleted file mode 120000index 5dcab58e1..000000000--- a/plugins/gemini/skills+++ /dev/null@@ -1 +0,0 @@-../../skills\ No newline at end of filediff --git a/plugins/worktrunk/CLAUDE.md b/plugins/worktrunk/CLAUDE.mdindex fdb03b011..a2b142644 100644--- a/plugins/worktrunk/CLAUDE.md+++ b/plugins/worktrunk/CLAUDE.md@@ -2,28 +2,34 @@## Directory Layout-One plugin payload, two tools. The plugin lives entirely in this directory-(`plugins/worktrunk/`); only the two loader-mandated marketplace pointers stay-at the repo root, because Claude Code and Codex each hardcode their marketplace-path with no fallback.+This directory (`plugins/worktrunk/`) is the Claude Code + Codex payload. Each+tool hardcodes its loader path with no fallback, so the repo root carries one+pointer per tool: Claude's and Codex's both `source → ./plugins/worktrunk`,+while Gemini resolves its extension at the repo root itself (see repo CLAUDE.md+→ "Plugin Layout"; Gemini's hooks call the canonical `hooks/wt.sh` below).```worktrunk/ ← repo root = marketplace root├── .claude-plugin/marketplace.json ← Claude pointer (source → ./plugins/worktrunk)├── .agents/plugins/marketplace.json← Codex pointer (source → ./plugins/worktrunk)-└── plugins/worktrunk/ ← plugin root (both tools resolve source here)+├── gemini-extension.json ← Gemini manifest (extensionPath = repo root)+├── hooks/hooks.json ← Gemini activity hooks (call the wt.sh below)+├── skills -> (this dir) ← Gemini reads ${extensionPath}/skills = repo-root skills/+└── plugins/worktrunk/ ← plugin root (Claude + Codex resolve source here)├── plugin.json ← Claude manifest (NO .claude-plugin/ wrapper —│ the wrapper is marketplace-root-only)├── .codex-plugin/plugin.json ← Codex manifest (Codex's required wrapper)├── hooks/hooks.json ← Claude activity + WorktreeCreate/Remove hooks- ├── hooks/wt.sh ← hook helper (referenced via ${CLAUDE_PLUGIN_ROOT})- ├── skills -> ../../skills ← symlink; single-sources skills across both- │ plugins and the docs auto-sync+ ├── hooks/wt.sh ← canonical hook shim; Claude/Codex reach it via+ │ ${CLAUDE_PLUGIN_ROOT}, Gemini via+ │ ${extensionPath}/plugins/worktrunk/hooks/wt.sh+ ├── skills -> ../../skills ← symlink; single-sources skills across all+ │ tools and the docs auto-sync├── CLAUDE.md / README.md└── (Codex ships no hooks — see repo CLAUDE.md → "Plugin Layout")```-Path resolution differs by tool, both verified end-to-end against the real CLIs:+Path resolution differs by tool, all verified end-to-end against the real CLIs:- **Claude**: `.claude-plugin/marketplace.json` `source: "./plugins/worktrunk"`.Claude reads `plugins/worktrunk/plugin.json` (at the plugin root, *not* a@@ -34,10 +40,15 @@ Path resolution differs by tool, both verified end-to-end against the real CLIs:`{ "source": "local", "path": "./plugins/worktrunk" }`. Codex reads`plugins/worktrunk/.codex-plugin/plugin.json`. `skills: "./skills/"` resolvesthrough the same symlink.+- **Gemini**: `gemini-extension.json` at the repo root; `${extensionPath}` is+ the repo root, so `${extensionPath}/skills/` is the repo-root `skills/`+ directly and `hooks/hooks.json` (repo root) calls the canonical shim at+ `${extensionPath}/plugins/worktrunk/hooks/wt.sh`. No symlink or copy.-Each Claude skill directory must be listed in `plugin.json`'s `skills` array;-Codex picks up the whole `skills/` dir via the symlink (accepted tradeoff — see-repo CLAUDE.md → "Plugin Layout").+Each Claude skill directory must be listed in `plugin.json`'s `skills` array+(Claude has no auto-discovery — `test_plugin_layout_is_consolidated` enforces+that every repo-root skill is listed); Codex and Gemini pick up the whole+`skills/` dir (accepted tradeoff — see repo CLAUDE.md → "Plugin Layout").## Known Limitationsdiff --git a/tests/integration_tests/config_show.rs b/tests/integration_tests/config_show.rsindex 466d62eae..548c74531 100644--- a/tests/integration_tests/config_show.rs+++ b/tests/integration_tests/config_show.rs@@ -3615,28 +3615,25 @@ fn test_codex_plugin_metadata_is_valid_json() {assert_eq!(marketplace["interface"]["displayName"], "Worktrunk");}-/// Claude Code + Codex share `plugins/worktrunk/`; Gemini gets its own-/// `plugins/gemini/`. Every tool's payload lives under `plugins/`, leaving only-/// loader-mandated pointers at the repo root. Verified end-to-end against the-/// real CLIs: Claude (claude-cli 2.1.x) wants its manifest at the plugin root-/// with NO `.claude-plugin/` wrapper (`source: "./plugins/worktrunk"` +-/// `<subdir>/.claude-plugin/` fails "Plugin not found"); Gemini (gemini-cli-/// 0.42) hard-probes `${extensionPath}/{hooks,skills}/` with no path-/// indirection and `install` *copies* the extension dir, so it must be-/// self-contained (bundled `wt.sh`, no `../worktrunk` reference).+/// Claude Code + Codex share `plugins/worktrunk/`; Gemini's manifest is a+/// third loader-mandated repo-root pointer (`gemini-extension.json` ++/// `hooks/hooks.json` — Gemini hard-probes `${extensionPath}/{hooks,skills}/`+/// at the extension root with no path indirection). Verified end-to-end+/// against the real CLIs: Claude (claude-cli 2.1.x) wants its manifest at the+/// plugin root with NO `.claude-plugin/` wrapper (`source:+/// "./plugins/worktrunk"` + `<subdir>/.claude-plugin/` fails "Plugin not+/// found"); Gemini (gemini-cli 0.42) resolves the extension at the repo root,+/// so `${extensionPath}/skills/` is the real single-sourced repo-root+/// `skills/` and its hooks call the canonical+/// `${extensionPath}/plugins/worktrunk/hooks/wt.sh` — no symlink, no bundled+/// copy, and `gemini extensions install owner/repo` works natively.///-/// Gemini install constraints (the manifest moving under `plugins/gemini/`-/// trades these away — install via a local path, `gemini extensions install-/// <repo>/plugins/gemini`, until a `wt config plugins gemini install` command-/// exists): github-URL install (`owner/repo`) reads `<clone-root>/-/// gemini-extension.json` and so can't see the manifest; and `fs.cp` rewrites-/// the relative `skills` symlink to an absolute path, so the skills resolve-/// only while the source repo stays in place (a git/URL install loses them to-/// the deleted tempdir — silently empty). Robust fix = bundle copied SKILL.md-/// trees at release time, drift-guarded like `wt.sh`; tracked with the install-/// command. Duplicated-/// strings/shims can't be `include!`d into JSON, so this test is the drift-/// guard.+/// Duplicated strings can't be `include!`d into JSON, so this test is the+/// drift guard: the Claude marketplace/manifest descriptions stay+/// byte-identical, every product description shares the canonical opening+/// sentence, and every repo-root skill is listed in the Claude manifest+/// (Claude has no skill auto-discovery — an unlisted skill is silently+/// dropped).#[test]fn test_plugin_layout_is_consolidated() {let root = std::path::Path::new(env!("CARGO_MANIFEST_DIR"));@@ -3672,12 +3669,17 @@ fn test_plugin_layout_is_consolidated() {".claude-plugin/marketplace.json and plugins/worktrunk/plugin.json descriptions drifted");- // Gemini extension: own payload dir, nothing at the repo root.+ // Gemini extension: manifest + hooks are loader-mandated repo-root+ // pointers (Gemini hard-probes ${extensionPath}/{hooks,skills}/ at the+ // extension root). Relocating to the root — instead of a plugins/gemini/+ // sibling — is what makes `gemini extensions install owner/repo` work and+ // lets the extension reuse the real repo-root skills/ + the canonical+ // worktrunk shim instead of a symlink and a bundled copy.assert!(- !root.join("gemini-extension.json").exists() && !root.join("hooks").exists(),- "Gemini extension lives in plugins/gemini/, not at the repo root"+ !root.join("plugins/gemini").exists(),+ "Gemini extension was relocated to the repo root; plugins/gemini/ must not exist");- let gemini = json("plugins/gemini/gemini-extension.json");+ let gemini = json("gemini-extension.json");assert_eq!(gemini["name"], "worktrunk");assert!(gemini["description"]@@ -3685,25 +3687,72 @@ fn test_plugin_layout_is_consolidated() {.is_some_and(|d| !d.is_empty()),"gemini-extension.json needs a description (shown in `gemini extensions list`)");- // Gemini `install` copies the extension dir, so it must be self-contained:- // bundled wt.sh, hooks referencing it via ${extensionPath}/hooks/, never a- // cross-dir `../worktrunk` or the old `.claude-plugin/` path.+ // Gemini reuses the single-sourced repo-root skills/ (a real dir that+ // survives `gemini extensions install`'s copy) — not a symlink or bundle.assert!(- root.join("plugins/gemini/skills").is_symlink(),- "plugins/gemini/skills must be a symlink reusing the repo-root skills/"+ root.join("skills").is_dir() && !root.join("skills").is_symlink(),+ "repo-root skills/ must be a real directory Gemini resolves via ${{extensionPath}}/skills");- let gemini_hooks = read("plugins/gemini/hooks/hooks.json");+ // Gemini hooks call the canonical worktrunk shim by its real path — no+ // bundled ${extensionPath}/hooks/wt.sh, no cross-dir `../`, no old wrapper.+ let gemini_hooks = read("hooks/hooks.json");assert!(- gemini_hooks.contains("${extensionPath}/hooks/wt.sh")- && !gemini_hooks.contains("../worktrunk")+ gemini_hooks.contains("${extensionPath}/plugins/worktrunk/hooks/wt.sh")+ && !gemini_hooks.contains("${extensionPath}/hooks/wt.sh")+ && !gemini_hooks.contains("../")&& !gemini_hooks.contains(".claude-plugin/"),- "Gemini hooks must call the bundled ${{extensionPath}}/hooks/wt.sh (self-contained)"+ "Gemini hooks must call the canonical ${{extensionPath}}/plugins/worktrunk/hooks/wt.sh");- assert_eq!(- read("plugins/gemini/hooks/wt.sh"),- read("plugins/worktrunk/hooks/wt.sh"),- "bundled Gemini wt.sh drifted from the canonical plugins/worktrunk/hooks/wt.sh"+ assert!(+ !root.join("hooks/wt.sh").exists(),+ "no bundled Gemini wt.sh — hooks reference the canonical worktrunk shim");++ // Claude has no skill auto-discovery, so every repo-root skill dir MUST be+ // listed explicitly in plugin.json — otherwise a new skill is silently+ // invisible to Claude while Codex/Gemini (whole-dir) pick it up.+ let listed: std::collections::BTreeSet<&str> = claude["skills"]+ .as_array()+ .expect("plugin.json `skills` must be an array")+ .iter()+ .map(|v| v.as_str().unwrap())+ .collect();+ for entry in fs::read_dir(root.join("skills")).unwrap() {+ let entry = entry.unwrap();+ if entry.file_type().unwrap().is_dir() {+ let listed_form = format!("./skills/{}", entry.file_name().to_string_lossy());+ assert!(+ listed.contains(listed_form.as_str()),+ "repo-root skill {listed_form} is not in plugins/worktrunk/plugin.json \+ `skills` (Claude has no auto-discovery — add it or it is silently dropped)"+ );+ }+ }++ // The product description must not drift across tools. Byte-identical is+ // schema-impossible (Codex omits the activity clause, Gemini says+ // "extension"), but every manifest shares the canonical opening sentence.+ const STEM: &str =+ "Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows.";+ let codex = json("plugins/worktrunk/.codex-plugin/plugin.json");+ for (label, val) in [+ ("plugins/worktrunk/plugin.json", &claude["description"]),+ (+ ".claude-plugin/marketplace.json",+ &claude_mkt["plugins"][0]["description"],+ ),+ (+ "plugins/worktrunk/.codex-plugin/plugin.json",+ &codex["description"],+ ),+ ("gemini-extension.json", &gemini["description"]),+ ] {+ let val = val.as_str().unwrap();+ assert!(+ val.starts_with(STEM),+ "{label} description must start with the canonical product sentence; got: {val}"+ );+ }}// ==================== Plugin Install-Statusline Tests ====================