Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

feat(plugin): self-contained Gemini CLI extension in plugins/gemini/ (#2803)

Maximilian Roos70711414de90
diff --git a/CLAUDE.md b/CLAUDE.md
index 3f417ed65..2d3de616e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -172,6 +172,8 @@ Config docs (`USER_CONFIG_START`/`PROJECT_CONFIG_START` sections in `src/cli/mod
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.
+**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.
+
**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.
diff --git a/plugins/gemini/gemini-extension.json b/plugins/gemini/gemini-extension.json
new file mode 100644
index 000000000..0925d211e
--- /dev/null
+++ b/plugins/gemini/gemini-extension.json
@@ -0,0 +1,5 @@
+{
+ "name": "worktrunk",
+ "version": "0.1.0",
+ "description": "Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows. This extension provides configuration guidance (LLM commit messages, project hooks, worktree paths) and automatic activity tracking (🤖/💬 indicators in `wt list` showing active Gemini CLI sessions)."
+}
diff --git a/plugins/gemini/hooks/hooks.json b/plugins/gemini/hooks/hooks.json
new file mode 100644
index 000000000..c00520f23
--- /dev/null
+++ b/plugins/gemini/hooks/hooks.json
@@ -0,0 +1,34 @@
+{
+ "hooks": {
+ "BeforeAgent": [
+ {
+ "hooks": [
+ {
+ "type": "command",
+ "command": "bash \"${extensionPath}/hooks/wt.sh\" config state marker set 🤖 || true"
+ }
+ ]
+ }
+ ],
+ "AfterAgent": [
+ {
+ "hooks": [
+ {
+ "type": "command",
+ "command": "bash \"${extensionPath}/hooks/wt.sh\" config state marker set 💬 || true"
+ }
+ ]
+ }
+ ],
+ "SessionEnd": [
+ {
+ "hooks": [
+ {
+ "type": "command",
+ "command": "bash \"${extensionPath}/hooks/wt.sh\" config state marker clear || true"
+ }
+ ]
+ }
+ ]
+ }
+}
diff --git a/plugins/gemini/hooks/wt.sh b/plugins/gemini/hooks/wt.sh
new file mode 100755
index 000000000..a7a4a72e1
--- /dev/null
+++ b/plugins/gemini/hooks/wt.sh
@@ -0,0 +1,39 @@
+#!/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
new file mode 120000
index 000000000..5dcab58e1
--- /dev/null
+++ b/plugins/gemini/skills
@@ -0,0 +1 @@
+../../skills
\ No newline at end of file
diff --git a/tests/integration_tests/config_show.rs b/tests/integration_tests/config_show.rs
index 67acbfd38..466d62eae 100644
--- a/tests/integration_tests/config_show.rs
+++ b/tests/integration_tests/config_show.rs
@@ -3615,14 +3615,28 @@ fn test_codex_plugin_metadata_is_valid_json() {
assert_eq!(marketplace["interface"]["displayName"], "Worktrunk");
}
-/// The Claude Code and Codex plugins share one payload dir, `plugins/worktrunk/`.
-/// Both marketplace pointers must stay at the repo root (each tool hardcodes its
-/// path) and point `source` at that subdir; the Claude manifest sits at the
-/// plugin root with NO `.claude-plugin/` wrapper (the wrapper is
-/// marketplace-root-only — verified end-to-end against claude-cli 2.1.x:
-/// `source: "./plugins/worktrunk"` + manifest at `<subdir>/.claude-plugin/`
-/// fails "Plugin not found"). The duplicated description string can't be
-/// `include!`d into JSON, so this test is the drift guard.
+/// 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).
+///
+/// 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.
#[test]
fn test_plugin_layout_is_consolidated() {
let root = std::path::Path::new(env!("CARGO_MANIFEST_DIR"));
@@ -3657,6 +3671,39 @@ fn test_plugin_layout_is_consolidated() {
claude_mkt["plugins"][0]["description"], claude["description"],
".claude-plugin/marketplace.json and plugins/worktrunk/plugin.json descriptions drifted"
);
+
+ // Gemini extension: own payload dir, nothing at the repo root.
+ assert!(
+ !root.join("gemini-extension.json").exists() && !root.join("hooks").exists(),
+ "Gemini extension lives in plugins/gemini/, not at the repo root"
+ );
+ let gemini = json("plugins/gemini/gemini-extension.json");
+ assert_eq!(gemini["name"], "worktrunk");
+ assert!(
+ gemini["description"]
+ .as_str()
+ .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.
+ assert!(
+ root.join("plugins/gemini/skills").is_symlink(),
+ "plugins/gemini/skills must be a symlink reusing the repo-root skills/"
+ );
+ let gemini_hooks = read("plugins/gemini/hooks/hooks.json");
+ assert!(
+ gemini_hooks.contains("${extensionPath}/hooks/wt.sh")
+ && !gemini_hooks.contains("../worktrunk")
+ && !gemini_hooks.contains(".claude-plugin/"),
+ "Gemini hooks must call the bundled ${{extensionPath}}/hooks/wt.sh (self-contained)"
+ );
+ 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"
+ );
}
// ==================== Plugin Install-Statusline Tests ====================