Skip to content

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.md
index 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 Safety
diff --git a/plugins/gemini/gemini-extension.json b/gemini-extension.json
similarity index 100%
rename from plugins/gemini/gemini-extension.json
rename to gemini-extension.json
diff --git a/plugins/gemini/hooks/hooks.json b/hooks/hooks.json
similarity index 53%
rename from plugins/gemini/hooks/hooks.json
rename to hooks/hooks.json
index 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.sh
deleted file mode 100755
index 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/skills
deleted file mode 120000
index 5dcab58e1..000000000
--- a/plugins/gemini/skills
+++ /dev/null
@@ -1 +0,0 @@
-../../skills
\ No newline at end of file
diff --git a/plugins/worktrunk/CLAUDE.md b/plugins/worktrunk/CLAUDE.md
index 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/"` resolves
through 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 Limitations
diff --git a/tests/integration_tests/config_show.rs b/tests/integration_tests/config_show.rs
index 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 ====================