Skip to content

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

Ship Codex activity-marker hooks as a separate hooks-only plugin (#4707)

Worktrunk Bota29ee2b13b03
diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json
index eb1f7259f..583bb69c1 100644
--- a/.agents/plugins/marketplace.json
+++ b/.agents/plugins/marketplace.json
@@ -14,6 +14,17 @@
"installation": "AVAILABLE"
},
"category": "Productivity"
+ },
+ {
+ "name": "worktrunk-markers",
+ "source": {
+ "source": "local",
+ "path": "./plugins/worktrunk-markers"
+ },
+ "policy": {
+ "installation": "AVAILABLE"
+ },
+ "category": "Productivity"
}
]
}
diff --git a/.gitattributes b/.gitattributes
index 1189cdeda..89a409ffe 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -34,6 +34,7 @@ templates/* text eol=lf
# label specified"). The hook shim is only ever run by cmd.exe, so pin its
# checkout to CRLF regardless of the platform cloning it.
plugins/worktrunk/hooks/*.cmd text eol=crlf
+plugins/worktrunk-markers/hooks/*.cmd text eol=crlf
# A fixture's object store and index are git's own binary formats, but git only
# calls a file binary when it finds a NUL in the first 8000 bytes, and a small
# enough zlib object may have none. Those diff as text, so `git diff` writes raw
diff --git a/docs/src/content/docs/claude-code.md b/docs/src/content/docs/claude-code.md
index adebe1fba..556cd995f 100644
--- a/docs/src/content/docs/claude-code.md
+++ b/docs/src/content/docs/claude-code.md
@@ -44,9 +44,12 @@ Manual equivalent:
```bash
codex plugin marketplace add max-sixty/worktrunk
codex plugin add worktrunk@worktrunk
+codex plugin add worktrunk-markers@worktrunk
```
-`wt config plugins codex uninstall` removes the plugin and its marketplace entry.
+`worktrunk` carries the skills; `worktrunk-markers` carries only the activity-marker hooks, so skill updates don't make Codex ask to approve the hooks again. An install that predates the split has only `worktrunk`, whose markers stop once it updates; add the markers with `codex plugin add worktrunk-markers@worktrunk`.
+
+`wt config plugins codex uninstall` removes both plugins and their marketplace entry.
### OpenCode
diff --git a/plugins/worktrunk-markers/.codex-plugin/plugin.json b/plugins/worktrunk-markers/.codex-plugin/plugin.json
new file mode 100644
index 000000000..5f2e24e8d
--- /dev/null
+++ b/plugins/worktrunk-markers/.codex-plugin/plugin.json
@@ -0,0 +1,70 @@
+{
+ "name": "worktrunk-markers",
+ "description": "Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows. This plugin shows each Codex session's activity (πŸ€– working, πŸ’¬ waiting) in wt list.",
+ "author": {
+ "name": "Worktrunk",
+ "url": "https://github.com/max-sixty/worktrunk"
+ },
+ "homepage": "https://worktrunk.dev",
+ "repository": "https://github.com/max-sixty/worktrunk",
+ "license": "MIT OR Apache-2.0",
+ "keywords": ["git", "worktree", "codex", "agent"],
+ "hooks": {
+ "hooks": {
+ "UserPromptSubmit": [
+ {
+ "hooks": [
+ {
+ "type": "command",
+ "command": "bash \"$PLUGIN_ROOT/hooks/wt.sh\" config state marker set πŸ€– || true",
+ "commandWindows": "cmd /d /c call \"${PLUGIN_ROOT}\\hooks\\wt.cmd\" config state marker set πŸ€–"
+ }
+ ]
+ }
+ ],
+ "PermissionRequest": [
+ {
+ "matcher": "",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "bash \"$PLUGIN_ROOT/hooks/wt.sh\" config state marker set πŸ’¬ || true",
+ "commandWindows": "cmd /d /c call \"${PLUGIN_ROOT}\\hooks\\wt.cmd\" config state marker set πŸ’¬"
+ }
+ ]
+ }
+ ],
+ "Stop": [
+ {
+ "hooks": [
+ {
+ "type": "command",
+ "command": "bash \"$PLUGIN_ROOT/hooks/wt.sh\" config state marker set πŸ’¬ || true",
+ "commandWindows": "cmd /d /c call \"${PLUGIN_ROOT}\\hooks\\wt.cmd\" config state marker set πŸ’¬"
+ }
+ ]
+ }
+ ],
+ "SessionEnd": [
+ {
+ "hooks": [
+ {
+ "type": "command",
+ "command": "bash \"$PLUGIN_ROOT/hooks/wt.sh\" config state marker clear || true",
+ "commandWindows": "cmd /d /c call \"${PLUGIN_ROOT}\\hooks\\wt.cmd\" config state marker clear",
+ "timeout": 3
+ }
+ ]
+ }
+ ]
+ }
+ },
+ "interface": {
+ "displayName": "Worktrunk activity markers",
+ "shortDescription": "Show Codex session activity in wt list.",
+ "longDescription": "Marks the worktree a Codex session runs in as working or waiting, so wt list shows which sessions need attention.",
+ "developerName": "Worktrunk",
+ "category": "Productivity",
+ "websiteURL": "https://worktrunk.dev"
+ }
+}
diff --git a/plugins/worktrunk-markers/hooks/wt.cmd b/plugins/worktrunk-markers/hooks/wt.cmd
new file mode 100644
index 000000000..fd1eeaaeb
--- /dev/null
+++ b/plugins/worktrunk-markers/hooks/wt.cmd
@@ -0,0 +1,58 @@
+@echo off
+rem Windows hook entrypoint: find Git Bash by installation path, avoiding the
+rem System32\bash.exe WSL launcher (#4007), then run the shared wt.sh.
+rem Usage: wt.cmd [args...]
+rem
+rem Codex uses the session shell, so commandWindows must parse in cmd and both
+rem PowerShell editions (#4239). `cmd /d /c call "${PLUGIN_ROOT}\hooks\wt.cmd"`
+rem starts with a command rather than a PowerShell string expression. `call`
+rem avoids cmd's initial-quote stripping; /d disables AutoRun for this cmd hop.
+rem The outer cmd, if Codex uses one, still runs its own AutoRun. A cmd-session
+rem lookup of the bare `cmd` can also resolve an executable in the project cwd.
+rem
+rem Always exit 0: markers are best-effort, and cmd's `|| exit /b 0` cannot live
+rem in the cross-shell command string. Diagnostics still go to stderr.
+rem
+rem Every branch here is a bare `goto` or `call`: `if <cond> <cmd1> & <cmd2>`
+rem runs cmd2 unconditionally, and `if <cond> <cmd1> || <cmd2>` tests the `if`
+rem rather than cmd1, so neither connector can carry the control flow.
+setlocal EnableExtensions
+rem Clear the local: `setlocal` inherits the caller's environment, and Codex
+rem hands each hook the session env snapshot, so an inherited BASH would name
+rem what every event runs.
+set "BASH="
+
+rem Ask Git for its runtime path so PATH shims resolve to the installation
+rem they launch. Ignore GIT_EXEC_PATH in the query: it overrides the installed
+rem helper path. The hook itself keeps the caller's environment.
+rem cmd's PATH modifier finds the first git.exe on PATH without consulting
+rem the project directory or spawning another command interpreter for lookup.
+for %%I in (git.exe) do if not "%%~$PATH:I"=="" call :derive "%%~$PATH:I"
+
+if not defined BASH goto :missing
+
+"%BASH%" "%~dp0wt.sh" %*
+exit /b 0
+
+rem Git for Windows reports <install>/<runtime>/libexec/git-core. The bin
+rem wrapper sets up MSYS for wt.sh; usr/bin is the runtime Bash itself.
+:derive
+for /f "delims=" %%I in ('set "GIT_EXEC_PATH=" ^& "%~1" --exec-path 2^>nul') do call :runtime "%%I"
+goto :eof
+
+:runtime
+rem Normalize Git's forward slashes before matching its runtime suffix.
+set "GIT_RUNTIME=%~1"
+set "GIT_RUNTIME=%GIT_RUNTIME:/=\%"
+if /i not "%GIT_RUNTIME:~-17%"=="\libexec\git-core" goto :eof
+call :accept "%GIT_RUNTIME%\..\..\..\bin\bash.exe"
+if not defined BASH call :accept "%GIT_RUNTIME%\..\..\..\usr\bin\bash.exe"
+goto :eof
+
+:accept
+if exist "%~1" set "BASH=%~f1"
+goto :eof
+
+:missing
+echo worktrunk: Git for Windows is required but bash.exe was not found. Install from https://git-scm.com/download/win 1>&2
+exit /b 0
diff --git a/plugins/worktrunk-markers/hooks/wt.sh b/plugins/worktrunk-markers/hooks/wt.sh
new file mode 100755
index 000000000..3be4697d4
--- /dev/null
+++ b/plugins/worktrunk-markers/hooks/wt.sh
@@ -0,0 +1,45 @@
+#!/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...]
+
+# Clear WT before the branches below: on Windows they leave it unset when
+# neither git-wt.exe nor wt is on PATH, and a hook is handed the caller's whole
+# environment -- so an inherited WT would be what the final check accepts and
+# runs, Windows Terminal included.
+WT=""
+
+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/#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/worktrunk/.codex-plugin/plugin.json b/plugins/worktrunk/.codex-plugin/plugin.json
index 8c398e732..a41907ca5 100644
--- a/plugins/worktrunk/.codex-plugin/plugin.json
+++ b/plugins/worktrunk/.codex-plugin/plugin.json
@@ -10,54 +10,7 @@
"license": "MIT OR Apache-2.0",
"keywords": ["git", "worktree", "codex", "agent"],
"hooks": {
- "hooks": {
- "UserPromptSubmit": [
- {
- "hooks": [
- {
- "type": "command",
- "command": "bash \"$PLUGIN_ROOT/hooks/wt.sh\" config state marker set πŸ€– || true",
- "commandWindows": "cmd /d /c call \"${PLUGIN_ROOT}\\hooks\\wt.cmd\" config state marker set πŸ€–"
- }
- ]
- }
- ],
- "PermissionRequest": [
- {
- "matcher": "",
- "hooks": [
- {
- "type": "command",
- "command": "bash \"$PLUGIN_ROOT/hooks/wt.sh\" config state marker set πŸ’¬ || true",
- "commandWindows": "cmd /d /c call \"${PLUGIN_ROOT}\\hooks\\wt.cmd\" config state marker set πŸ’¬"
- }
- ]
- }
- ],
- "Stop": [
- {
- "hooks": [
- {
- "type": "command",
- "command": "bash \"$PLUGIN_ROOT/hooks/wt.sh\" config state marker set πŸ’¬ || true",
- "commandWindows": "cmd /d /c call \"${PLUGIN_ROOT}\\hooks\\wt.cmd\" config state marker set πŸ’¬"
- }
- ]
- }
- ],
- "SessionEnd": [
- {
- "hooks": [
- {
- "type": "command",
- "command": "bash \"$PLUGIN_ROOT/hooks/wt.sh\" config state marker clear || true",
- "commandWindows": "cmd /d /c call \"${PLUGIN_ROOT}\\hooks\\wt.cmd\" config state marker clear",
- "timeout": 3
- }
- ]
- }
- ]
- }
+ "hooks": {}
},
"interface": {
"displayName": "Worktrunk",
diff --git a/plugins/worktrunk/AGENTS.md b/plugins/worktrunk/AGENTS.md
index 0be095a22..565dd8540 100644
--- a/plugins/worktrunk/AGENTS.md
+++ b/plugins/worktrunk/AGENTS.md
@@ -1,13 +1,14 @@
# Worktrunk plugin
-The repository root is the marketplace for Claude Code and Codex and the Gemini extension root. Claude and Codex both install plugins/worktrunk; Gemini reads the root manifest. Keep each manifest at the path its loader requires.
+The repository root is the marketplace for Claude Code and Codex and the Gemini extension root. Claude and Codex both install plugins/worktrunk; Codex also installs plugins/worktrunk-markers; Gemini reads the root manifest. Keep each manifest at the path its loader requires.
## Plugin layout
- Repo-local maintainer skills live in .claude/skills/; .agents/skills points there. This symlink does not work on Windows checkouts with core.symlinks=false.
-- Claude discovers plugins/worktrunk/hooks/hooks.json by convention. The Codex manifest defines hooks inline so Codex does not load Claude events from that same file. Gemini has its own root hooks/hooks.json.
+- Claude discovers plugins/worktrunk/hooks/hooks.json by convention. The worktrunk Codex manifest declares an empty inline `hooks` object so Codex does not load Claude events from that same file; an absent key makes Codex read it and warn at startup. Gemini has its own root hooks/hooks.json.
+- Codex hooks live in plugins/worktrunk-markers, a hooks-only plugin. Codex binds hook approval to a fingerprint of every file in the plugin directory, so hooks beside the skills would need review after each skill or docs change. Keep that directory to its manifest and shims: any change there, including a manifest `version` bump, makes every Codex user approve the hooks again. Its hooks/wt.sh and hooks/wt.cmd are real copies of the plugins/worktrunk shims, since Codex's installer drops symlinks; test_codex_markers_shims_match keeps them identical.
- Claude hooks run `wt config plugins claude hook`, which dispatches on the payload event. Keep commands literal for Anthropic's plugin directory validator, and `$CLAUDE_PLUGIN_ROOT` unbraced for fish.
-- All three integrations call plugins/worktrunk/hooks/wt.sh. On Windows, Codex commandWindows calls hooks/wt.cmd to find Git Bash before running wt.sh. The command must parse in cmd.exe, Windows PowerShell, and pwsh; test it in all three shells with a plugin path containing spaces. Marker failures must not raise hook errors.
+- Claude and Gemini call plugins/worktrunk/hooks/wt.sh; Codex calls its copy. On Windows, Codex commandWindows calls hooks/wt.cmd to find Git Bash before running wt.sh. The command must parse in cmd.exe, Windows PowerShell, and pwsh; test it in all three shells with a plugin path containing spaces. Marker failures must not raise hook errors.
- The Codex manifest uses the native PLUGIN_ROOT variable, braced as `${PLUGIN_ROOT}` in Windows commands for Codex's textual substitution. SessionEnd has a three-second timeout, Codex's event ceiling.
- The shared skills mirror exposes wt-switch-create to Codex and Gemini, even though only Claude can switch the current session directory. Keep one authored skill tree.
- hooks/register.tsx is the plugin's one Claude Code hooks module (the early-access function hooks API), named under `modules` in hooks/hooks.json; it serves `/wt-diff`. types/index.d.ts is its state contract and tests/ its suite. Claude Code releases without modules drop the key and still load `hooks`, and Codex and Gemini never read it. Work on it with `claude --plugin-dir plugins/worktrunk`, which overrides an installed copy, and check it with `claude plugin validate plugins/worktrunk` and `claude plugin test plugins/worktrunk`.
diff --git a/plugins/worktrunk/skills/worktrunk/reference/claude-code.md b/plugins/worktrunk/skills/worktrunk/reference/claude-code.md
index 4f286a961..c4d9e72bf 100644
--- a/plugins/worktrunk/skills/worktrunk/reference/claude-code.md
+++ b/plugins/worktrunk/skills/worktrunk/reference/claude-code.md
@@ -40,9 +40,12 @@ Manual equivalent:
```bash
codex plugin marketplace add max-sixty/worktrunk
codex plugin add worktrunk@worktrunk
+codex plugin add worktrunk-markers@worktrunk
```
-`wt config plugins codex uninstall` removes the plugin and its marketplace entry.
+`worktrunk` carries the skills; `worktrunk-markers` carries only the activity-marker hooks, so skill updates don't make Codex ask to approve the hooks again. An install that predates the split has only `worktrunk`, whose markers stop once it updates; add the markers with `codex plugin add worktrunk-markers@worktrunk`.
+
+`wt config plugins codex uninstall` removes both plugins and their marketplace entry.
### OpenCode
diff --git a/skills/worktrunk/reference/claude-code.md b/skills/worktrunk/reference/claude-code.md
index 4f286a961..c4d9e72bf 100644
--- a/skills/worktrunk/reference/claude-code.md
+++ b/skills/worktrunk/reference/claude-code.md
@@ -40,9 +40,12 @@ Manual equivalent:
```bash
codex plugin marketplace add max-sixty/worktrunk
codex plugin add worktrunk@worktrunk
+codex plugin add worktrunk-markers@worktrunk
```
-`wt config plugins codex uninstall` removes the plugin and its marketplace entry.
+`worktrunk` carries the skills; `worktrunk-markers` carries only the activity-marker hooks, so skill updates don't make Codex ask to approve the hooks again. An install that predates the split has only `worktrunk`, whose markers stop once it updates; add the markers with `codex plugin add worktrunk-markers@worktrunk`.
+
+`wt config plugins codex uninstall` removes both plugins and their marketplace entry.
### OpenCode
diff --git a/src/cli/config.rs b/src/cli/config.rs
index fa15b1d12..8f82fffd4 100644
--- a/src/cli/config.rs
+++ b/src/cli/config.rs
@@ -294,24 +294,28 @@ $ wt config plugins omp uninstall
// Ordering: action + inverse adjacent (install, uninstall).
#[derive(Subcommand)]
pub enum ConfigPluginsCodexCommand {
- /// Install the Worktrunk plugin
+ /// Install the Worktrunk plugins
#[command(
- after_long_help = r#"Adds the Worktrunk plugin from the marketplace and installs it. Equivalent to:
+ after_long_help = r#"Adds the Worktrunk marketplace and installs its two plugins: `worktrunk` for the skills and `worktrunk-markers` for the activity-marker hooks. Equivalent to:
```console
$ codex plugin marketplace add max-sixty/worktrunk
$ codex plugin add worktrunk@worktrunk
+$ codex plugin add worktrunk-markers@worktrunk
```
+The hooks ship separately because Codex asks for hook approval again whenever anything in a plugin changes. Skill updates leave the markers plugin unchanged, so its hooks keep their approval.
+
Requires `codex` CLI."#
)]
Install,
- /// Remove the Worktrunk plugin
+ /// Remove the Worktrunk plugins
#[command(
- after_long_help = r#"Uninstalls the Worktrunk plugin from Codex and removes its marketplace. Equivalent to:
+ after_long_help = r#"Uninstalls the Worktrunk plugins from Codex and removes their marketplace. Equivalent to:
```console
+$ codex plugin remove worktrunk-markers@worktrunk
$ codex plugin remove worktrunk@worktrunk
$ codex plugin marketplace remove worktrunk
```
@@ -415,7 +419,7 @@ $ wt config plugins claude install-statusline
/// Codex plugin
#[command(
- after_long_help = r#"Bundles a configuration skill β€” documentation Codex can read to help set up LLM commits, project hooks, and worktree paths β€” plus activity-marker hooks that show πŸ€–/πŸ’¬ in `wt list` while a Codex session runs and clear the marker when it ends.
+ after_long_help = r#"Installs a configuration skill β€” documentation Codex can read to help set up LLM commits, project hooks, and worktree paths β€” and, as a separate plugin, activity-marker hooks that show πŸ€–/πŸ’¬ in `wt list` while a Codex session runs and clear the marker when it ends.
## Examples
diff --git a/src/commands/config/codex.rs b/src/commands/config/codex.rs
index 6b8f22cb9..ae04d4a59 100644
--- a/src/commands/config/codex.rs
+++ b/src/commands/config/codex.rs
@@ -9,8 +9,15 @@ use crate::output::prompt::{PromptResponse, prompt_yes_no_preview};
const MARKETPLACE_SOURCE: &str = "max-sixty/worktrunk";
const MARKETPLACE_NAME: &str = "worktrunk";
-/// `PLUGIN@MARKETPLACE` selector `codex plugin add` / `remove` take.
+/// `PLUGIN@MARKETPLACE` selectors `codex plugin add` / `remove` take.
+///
+/// The activity-marker hooks ship as their own plugin. Codex 0.164+ binds hook
+/// approval to a fingerprint of the whole plugin directory, so hooks bundled
+/// with the skills needed another review after every skill or docs change.
+/// The hooks-only plugin's fingerprint moves only when its hook commands or
+/// shims do.
const PLUGIN_SELECTOR: &str = "worktrunk@worktrunk";
+const MARKERS_PLUGIN_SELECTOR: &str = "worktrunk-markers@worktrunk";
/// Handle `wt config plugins codex install`.
pub fn handle_codex_install(yes: bool) -> Result<()> {
@@ -18,10 +25,10 @@ pub fn handle_codex_install(yes: bool) -> Result<()> {
if !yes {
match prompt_yes_no_preview(
- &cformat!("Install Worktrunk plugin for <bold>Codex</>?"),
+ &cformat!("Install Worktrunk plugins for <bold>Codex</>?"),
|| {
let commands = format!(
- "codex plugin marketplace add {MARKETPLACE_SOURCE}\ncodex plugin add {PLUGIN_SELECTOR}"
+ "codex plugin marketplace add {MARKETPLACE_SOURCE}\ncodex plugin add {PLUGIN_SELECTOR}\ncodex plugin add {MARKERS_PLUGIN_SELECTOR}"
);
eprintln!("{}", worktrunk::styling::format_bash_with_gutter(&commands));
},
@@ -37,14 +44,15 @@ pub fn handle_codex_install(yes: bool) -> Result<()> {
&["plugin", "marketplace", "add", MARKETPLACE_SOURCE],
)?;
- eprintln!("{}", progress_message("Installing plugin..."));
+ eprintln!("{}", progress_message("Installing plugins..."));
super::run_plugin_cli("codex", &["plugin", "add", PLUGIN_SELECTOR])?;
+ super::run_plugin_cli("codex", &["plugin", "add", MARKERS_PLUGIN_SELECTOR])?;
- eprintln!("{}", success_message("Codex plugin installed"));
- // The Codex plugin ships activity-marker hooks inline in its manifest
- // (`hooks` key in .codex-plugin/plugin.json), using `Stop` to return
- // πŸ€– β†’ πŸ’¬ and `SessionEnd` to clear the marker. See AGENTS.md β†’ "Plugin
- // Layout".
+ eprintln!("{}", success_message("Codex plugins installed"));
+ // The markers plugin ships activity-marker hooks inline in its manifest
+ // (`hooks` key in plugins/worktrunk-markers/.codex-plugin/plugin.json),
+ // using `Stop` to return πŸ€– β†’ πŸ’¬ and `SessionEnd` to clear the marker.
+ // See plugins/worktrunk/AGENTS.md β†’ "Plugin layout".
eprintln!(
"{}",
hint_message(cformat!(
@@ -61,10 +69,10 @@ pub fn handle_codex_uninstall(yes: bool) -> Result<()> {
if !yes {
match prompt_yes_no_preview(
- &cformat!("Uninstall Worktrunk plugin from <bold>Codex</>?"),
+ &cformat!("Uninstall Worktrunk plugins from <bold>Codex</>?"),
|| {
let commands = format!(
- "codex plugin remove {PLUGIN_SELECTOR}\ncodex plugin marketplace remove {MARKETPLACE_NAME}"
+ "codex plugin remove {MARKERS_PLUGIN_SELECTOR}\ncodex plugin remove {PLUGIN_SELECTOR}\ncodex plugin marketplace remove {MARKETPLACE_NAME}"
);
eprintln!("{}", worktrunk::styling::format_bash_with_gutter(&commands));
},
@@ -74,9 +82,11 @@ pub fn handle_codex_uninstall(yes: bool) -> Result<()> {
}
}
- // `codex plugin remove` exits 0 when the plugin is already gone, so this
- // step needs none of the tolerance the marketplace removal below does.
- eprintln!("{}", progress_message("Uninstalling plugin..."));
+ // `codex plugin remove` exits 0 when the plugin is already gone, so these
+ // steps need none of the tolerance the marketplace removal below does.
+ // That also covers installs from before the markers plugin existed.
+ eprintln!("{}", progress_message("Uninstalling plugins..."));
+ super::run_plugin_cli("codex", &["plugin", "remove", MARKERS_PLUGIN_SELECTOR])?;
super::run_plugin_cli("codex", &["plugin", "remove", PLUGIN_SELECTOR])?;
eprintln!(
@@ -89,7 +99,7 @@ pub fn handle_codex_uninstall(yes: bool) -> Result<()> {
is_marketplace_configured,
)?;
- eprintln!("{}", success_message("Codex plugin & marketplace removed"));
+ eprintln!("{}", success_message("Codex plugins & marketplace removed"));
Ok(())
}
@@ -113,7 +123,7 @@ fn require_codex_cli() -> Result<()> {
/// last entry under it, so a config whose key had been renamed looked exactly
/// like one a successful removal had just emptied, and the only reading that
/// let a second `uninstall` succeed was the one that reported every genuine
-/// failure as `Codex plugin & marketplace removed`. Codex's own list
+/// failure as `Codex plugins & marketplace removed`. Codex's own list
/// separates the two.
///
/// It also drops wt's copy of Codex's `CODEX_HOME` resolution. The child
diff --git a/tests/integration_tests/config_show.rs b/tests/integration_tests/config_show.rs
index 54ca79b5d..c80530a2b 100644
--- a/tests/integration_tests/config_show.rs
+++ b/tests/integration_tests/config_show.rs
@@ -5061,11 +5061,13 @@ fn test_plugins_codex_prompt_previews_commands(mut repo: TestRepo, temp_home: Te
[
"codex plugin marketplace add max-sixty/worktrunk",
"codex plugin add worktrunk@worktrunk",
+ "codex plugin add worktrunk-markers@worktrunk",
],
),
(
"uninstall",
[
+ "codex plugin remove worktrunk-markers@worktrunk",
"codex plugin remove worktrunk@worktrunk",
"codex plugin marketplace remove worktrunk",
],
@@ -5480,22 +5482,41 @@ fn test_codex_plugin_metadata_is_valid_json() {
.contains("claude-code"),
"plugin.json interface.websiteURL must point at the canonical site"
);
- // The Codex plugin ships activity-marker hooks *inline* in its manifest
- // (`hooks` object, not a path). This is the functional definition of its
- // Codex-native events, and it also overrides Codex's convention discovery
- // (an absent `hooks` key makes Codex auto-discover a `hooks/hooks.json` at
- // the plugin root). The Claude hooks file sits at that same conventional
- // `hooks/hooks.json` (Claude's loader discovers it there β€” #3417), but the
- // inline Codex override means Codex never loads it, so the #3362 collision
- // (Codex surfacing the *Claude* file's events) stays closed. `Stop`
- // returns πŸ€– to πŸ’¬ at turn end, and `SessionEnd` clears the marker when
- // the main thread ends. See AGENTS.md β†’ "Plugin Layout".
- let codex_hooks = plugin
+ // The skills plugin carries an empty inline `hooks` object. Codex
+ // auto-discovers `hooks/hooks.json` at the plugin root when the key is
+ // absent, and that path holds the Claude hooks file (Claude's loader
+ // discovers it there β€” #3417), so Codex would surface Claude's events
+ // (#3362) and warn at startup. The activity-marker hooks live in the
+ // hooks-only `worktrunk-markers` plugin instead: Codex fingerprints the
+ // whole plugin directory for hook approval, so hooks beside the skills
+ // needed another review after every skill or docs change (#4654).
+ assert_eq!(
+ plugin["hooks"],
+ serde_json::json!({"hooks": {}}),
+ "the worktrunk Codex manifest must carry an empty inline `hooks` object"
+ );
+ assert!(
+ !project_root
+ .join("plugins/worktrunk/.codex-plugin/hooks")
+ .exists(),
+ "the Codex wrapper dir must hold only plugin.json"
+ );
+
+ let markers: serde_json::Value = serde_json::from_str(
+ &fs::read_to_string(
+ project_root.join("plugins/worktrunk-markers/.codex-plugin/plugin.json"),
+ )
+ .unwrap(),
+ )
+ .unwrap();
+ assert_eq!(markers["name"], "worktrunk-markers");
+ // Exactly the Codex-native events β€” no Claude-only `Notification`,
+ // `WorktreeCreate`, or `WorktreeRemove`. `Stop` returns πŸ€– to πŸ’¬ at turn
+ // end, and `SessionEnd` clears the marker when the main thread ends.
+ let codex_hooks = markers
.get("hooks")
.and_then(|h| h.get("hooks"))
- .expect("Codex manifest must carry an inline `hooks` object");
- // Exactly the Codex-native events β€” no Claude-only `Notification`,
- // `WorktreeCreate`, or `WorktreeRemove`.
+ .expect("the markers manifest must carry an inline `hooks` object");
let mut events = codex_hooks
.as_object()
.unwrap()
@@ -5530,14 +5551,16 @@ fn test_codex_plugin_metadata_is_valid_json() {
!hooks_json.contains("CLAUDE_PLUGIN_ROOT"),
"Codex hooks must not reference the Claude-branded $CLAUDE_PLUGIN_ROOT alias"
);
- // Hooks are inline, so the wrapper dir still holds only plugin.json β€” no
- // separate hooks file, and the inline override keeps Codex off the shared
- // Claude `hooks/hooks.json`.
- assert!(
- !project_root
- .join("plugins/worktrunk/.codex-plugin/hooks")
- .exists(),
- "the Codex wrapper dir must hold only plugin.json"
+
+ assert_eq!(marketplace["plugins"][1]["name"], "worktrunk-markers");
+ assert_eq!(marketplace["plugins"][1]["source"]["source"], "local");
+ assert_eq!(
+ marketplace["plugins"][1]["source"]["path"],
+ "./plugins/worktrunk-markers"
+ );
+ assert_eq!(
+ marketplace["plugins"][1]["policy"]["installation"],
+ "AVAILABLE"
);
assert_eq!(marketplace["plugins"][0]["name"], "worktrunk");
// Source is a non-empty subdir object; a bare "./" is rejected by codex.
@@ -5555,6 +5578,59 @@ fn test_codex_plugin_metadata_is_valid_json() {
assert_eq!(marketplace["interface"]["displayName"], "Worktrunk");
}
+/// The hooks-only Codex plugin holds its manifest and real copies of the
+/// shared shims, nothing else. Codex fingerprints every file in a plugin
+/// directory for hook approval, so any other file there β€” or a manifest
+/// `version` a release would bump β€” makes every user approve the hooks again.
+/// Codex's installer drops symlinks, so the shims are copies, kept identical to
+/// the `plugins/worktrunk/hooks/` originals here.
+#[test]
+fn test_codex_markers_shims_match() {
+ let root = std::path::Path::new(env!("CARGO_MANIFEST_DIR"));
+ let markers = root.join("plugins/worktrunk-markers");
+
+ let mut files = Vec::new();
+ let mut dirs = vec![markers.clone()];
+ while let Some(dir) = dirs.pop() {
+ for entry in fs::read_dir(&dir).unwrap() {
+ let path = entry.unwrap().path();
+ assert!(
+ !path.is_symlink(),
+ "{} is a symlink; Codex's installer drops symlinks",
+ path.display()
+ );
+ if path.is_dir() {
+ dirs.push(path);
+ } else {
+ let rel = path.strip_prefix(&markers).unwrap();
+ files.push(path_slash::PathExt::to_slash_lossy(rel).into_owned());
+ }
+ }
+ }
+ files.sort_unstable();
+ assert_eq!(
+ files,
+ [".codex-plugin/plugin.json", "hooks/wt.cmd", "hooks/wt.sh"]
+ );
+
+ for name in ["wt.sh", "wt.cmd"] {
+ assert!(
+ fs::read(markers.join("hooks").join(name)).unwrap()
+ == fs::read(root.join("plugins/worktrunk/hooks").join(name)).unwrap(),
+ "plugins/worktrunk-markers/hooks/{name} drifted from plugins/worktrunk/hooks/{name}; copy it over"
+ );
+ }
+
+ let manifest: serde_json::Value = serde_json::from_str(
+ &fs::read_to_string(markers.join(".codex-plugin/plugin.json")).unwrap(),
+ )
+ .unwrap();
+ assert!(
+ manifest.get("version").is_none(),
+ "the markers manifest must not carry a `version`; changing it re-prompts hook approval"
+ );
+}
+
/// 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}/`
@@ -5833,6 +5909,7 @@ fn test_plugin_layout_is_consolidated() {
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");
+ let codex_markers = json("plugins/worktrunk-markers/.codex-plugin/plugin.json");
for (label, val) in [
(
"plugins/worktrunk/.claude-plugin/plugin.json",
@@ -5846,6 +5923,10 @@ fn test_plugin_layout_is_consolidated() {
"plugins/worktrunk/.codex-plugin/plugin.json",
&codex["description"],
),
+ (
+ "plugins/worktrunk-markers/.codex-plugin/plugin.json",
+ &codex_markers["description"],
+ ),
("gemini-extension.json", &gemini["description"]),
] {
let val = val.as_str().unwrap();
@@ -5863,7 +5944,8 @@ fn test_plugin_layout_is_consolidated() {
fn test_codex_hooks_carry_windows_commands() {
let root = std::path::Path::new(env!("CARGO_MANIFEST_DIR"));
let codex: serde_json::Value = serde_json::from_str(
- &fs::read_to_string(root.join("plugins/worktrunk/.codex-plugin/plugin.json")).unwrap(),
+ &fs::read_to_string(root.join("plugins/worktrunk-markers/.codex-plugin/plugin.json"))
+ .unwrap(),
)
.unwrap();
@@ -5904,7 +5986,9 @@ fn test_codex_hooks_carry_windows_commands() {
);
assert!(
windows.starts_with(r#"cmd /d /c call "${PLUGIN_ROOT}\hooks\wt.cmd" "#)
- && root.join("plugins/worktrunk/hooks/wt.cmd").is_file(),
+ && root
+ .join("plugins/worktrunk-markers/hooks/wt.cmd")
+ .is_file(),
"commandWindows must invoke the shipped shim through cmd /d /c call:\n{windows}"
);
assert!(
@@ -5984,7 +6068,8 @@ fn test_codex_windows_hook_commands_set_the_marker(repo: TestRepo) {
let root = std::path::Path::new(env!("CARGO_MANIFEST_DIR"));
let codex: serde_json::Value = serde_json::from_str(
- &fs::read_to_string(root.join("plugins/worktrunk/.codex-plugin/plugin.json")).unwrap(),
+ &fs::read_to_string(root.join("plugins/worktrunk-markers/.codex-plugin/plugin.json"))
+ .unwrap(),
)
.unwrap();
@@ -5993,7 +6078,7 @@ fn test_codex_windows_hook_commands_set_the_marker(repo: TestRepo) {
fs::create_dir_all(plugin_root.join("hooks")).unwrap();
for name in ["wt.cmd", "wt.sh"] {
fs::copy(
- root.join("plugins/worktrunk/hooks").join(name),
+ root.join("plugins/worktrunk-markers/hooks").join(name),
plugin_root.join("hooks").join(name),
)
.unwrap();
diff --git a/tests/snapshots/integration__integration_tests__config_show__plugins_codex_install.snap b/tests/snapshots/integration__integration_tests__config_show__plugins_codex_install.snap
index 8da6af2e5..b74a551ee 100644
--- a/tests/snapshots/integration__integration_tests__config_show__plugins_codex_install.snap
+++ b/tests/snapshots/integration__integration_tests__config_show__plugins_codex_install.snap
@@ -63,6 +63,6 @@ exit_code: 0
----- stderr -----
β—Ž Adding Codex plugin marketplace...
-β—Ž Installing plugin...
-βœ“ Codex plugin installed
+β—Ž Installing plugins...
+βœ“ Codex plugins installed
↳ Activity markers appear in wt list once a Codex session runs
diff --git a/tests/snapshots/integration__integration_tests__config_show__plugins_codex_install_plugin_add_fails.snap b/tests/snapshots/integration__integration_tests__config_show__plugins_codex_install_plugin_add_fails.snap
index bd06f9fb5..293d9c8e8 100644
--- a/tests/snapshots/integration__integration_tests__config_show__plugins_codex_install_plugin_add_fails.snap
+++ b/tests/snapshots/integration__integration_tests__config_show__plugins_codex_install_plugin_add_fails.snap
@@ -63,6 +63,6 @@ exit_code: 1
----- stderr -----
β—Ž Adding Codex plugin marketplace...
-β—Ž Installing plugin...
+β—Ž Installing plugins...
βœ— codex plugin add worktrunk@worktrunk failed (exit code 1)
  error: plugin add failed
diff --git a/tests/snapshots/integration__integration_tests__config_show__plugins_codex_uninstall.snap b/tests/snapshots/integration__integration_tests__config_show__plugins_codex_uninstall.snap
index 4e86198f4..58fb39552 100644
--- a/tests/snapshots/integration__integration_tests__config_show__plugins_codex_uninstall.snap
+++ b/tests/snapshots/integration__integration_tests__config_show__plugins_codex_uninstall.snap
@@ -62,6 +62,6 @@ exit_code: 0
----- stdout -----
----- stderr -----
-β—Ž Uninstalling plugin...
+β—Ž Uninstalling plugins...
β—Ž Removing Codex plugin marketplace...
-βœ“ Codex plugin & marketplace removed
+βœ“ Codex plugins & marketplace removed
diff --git a/tests/snapshots/integration__integration_tests__config_show__plugins_codex_uninstall_plugin_remove_fails.snap b/tests/snapshots/integration__integration_tests__config_show__plugins_codex_uninstall_plugin_remove_fails.snap
index 87e0a5302..134bf1eac 100644
--- a/tests/snapshots/integration__integration_tests__config_show__plugins_codex_uninstall_plugin_remove_fails.snap
+++ b/tests/snapshots/integration__integration_tests__config_show__plugins_codex_uninstall_plugin_remove_fails.snap
@@ -62,6 +62,6 @@ exit_code: 1
----- stdout -----
----- stderr -----
-β—Ž Uninstalling plugin...
-βœ— codex plugin remove worktrunk@worktrunk failed (exit code 1)
+β—Ž Uninstalling plugins...
+βœ— codex plugin remove worktrunk-markers@worktrunk failed (exit code 1)
  error: plugin remove failed
diff --git a/tests/snapshots/integration__integration_tests__config_show__plugins_codex_uninstall_surfaces_marketplace_remove_failure.snap b/tests/snapshots/integration__integration_tests__config_show__plugins_codex_uninstall_surfaces_marketplace_remove_failure.snap
index a634c945c..fc0361b7f 100644
--- a/tests/snapshots/integration__integration_tests__config_show__plugins_codex_uninstall_surfaces_marketplace_remove_failure.snap
+++ b/tests/snapshots/integration__integration_tests__config_show__plugins_codex_uninstall_surfaces_marketplace_remove_failure.snap
@@ -62,7 +62,7 @@ exit_code: 1
----- stdout -----
----- stderr -----
-β—Ž Uninstalling plugin...
+β—Ž Uninstalling plugins...
β—Ž Removing Codex plugin marketplace...
βœ— codex plugin marketplace remove worktrunk failed (exit code 1)
  error: marketplace remove failed
diff --git a/tests/snapshots/integration__integration_tests__config_show__plugins_codex_uninstall_tolerates_absent_marketplace.snap b/tests/snapshots/integration__integration_tests__config_show__plugins_codex_uninstall_tolerates_absent_marketplace.snap
index 4e86198f4..58fb39552 100644
--- a/tests/snapshots/integration__integration_tests__config_show__plugins_codex_uninstall_tolerates_absent_marketplace.snap
+++ b/tests/snapshots/integration__integration_tests__config_show__plugins_codex_uninstall_tolerates_absent_marketplace.snap
@@ -62,6 +62,6 @@ exit_code: 0
----- stdout -----
----- stderr -----
-β—Ž Uninstalling plugin...
+β—Ž Uninstalling plugins...
β—Ž Removing Codex plugin marketplace...
-βœ“ Codex plugin & marketplace removed
+βœ“ Codex plugins & marketplace removed
diff --git a/tests/snapshots/integration__integration_tests__config_show__plugins_codex_uninstall_tolerates_marketplace_missing_from_list.snap b/tests/snapshots/integration__integration_tests__config_show__plugins_codex_uninstall_tolerates_marketplace_missing_from_list.snap
index 4e86198f4..58fb39552 100644
--- a/tests/snapshots/integration__integration_tests__config_show__plugins_codex_uninstall_tolerates_marketplace_missing_from_list.snap
+++ b/tests/snapshots/integration__integration_tests__config_show__plugins_codex_uninstall_tolerates_marketplace_missing_from_list.snap
@@ -62,6 +62,6 @@ exit_code: 0
----- stdout -----
----- stderr -----
-β—Ž Uninstalling plugin...
+β—Ž Uninstalling plugins...
β—Ž Removing Codex plugin marketplace...
-βœ“ Codex plugin & marketplace removed
+βœ“ Codex plugins & marketplace removed
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_plugins_codex.snap b/tests/snapshots/integration__integration_tests__help__help_config_plugins_codex.snap
index e762ef257..767555465 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_plugins_codex.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_plugins_codex.snap
@@ -49,8 +49,8 @@ wt config plugins codex - Codex plugin
Usage: wt config plugins codex [OPTIONS] <COMMAND>
Commands:
- install Install the Worktrunk plugin
- uninstall Remove the Worktrunk plugin
+ install Install the Worktrunk plugins
+ uninstall Remove the Worktrunk plugins
Options:
-h, --help
@@ -72,7 +72,7 @@ Usage: wt config plugins codex [OPTIONS] <COMMAND>[0
-y, --yes
Skip approval prompts
-Bundles a configuration skill β€” documentation Codex can read to help set up LLM commits, project hooks, and worktree paths β€” plus activity-marker hooks that show πŸ€–/πŸ’¬ in wt list while a Codex session runs and clear the marker when it ends.
+Installs a configuration skill β€” documentation Codex can read to help set up LLM commits, project hooks, and worktree paths β€” and, as a separate plugin, activity-marker hooks that show πŸ€–/πŸ’¬ in wt list while a Codex session runs and clear the marker when it ends.
Examples
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_plugins_codex_install.snap b/tests/snapshots/integration__integration_tests__help__help_config_plugins_codex_install.snap
index 8fa0897b2..76592f4d5 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_plugins_codex_install.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_plugins_codex_install.snap
@@ -45,7 +45,7 @@ info:
success: true
exit_code: 0
----- stdout -----
-wt config plugins codex install - Install the Worktrunk plugin
+wt config plugins codex install - Install the Worktrunk plugins
Usage: wt config plugins codex install [OPTIONS]
@@ -69,10 +69,13 @@ Usage: wt config plugins codex install [OPTIONS]
-y, --yes
Skip approval prompts
-Adds the Worktrunk plugin from the marketplace and installs it. Equivalent to:
+Adds the Worktrunk marketplace and installs its two plugins: worktrunk for the skills and worktrunk-markers for the activity-marker hooks. Equivalent to:
  codex plugin marketplace add max-sixty/worktrunk
  codex plugin add worktrunk@worktrunk
+  codex plugin add worktrunk-markers@worktrunk
+
+The hooks ship separately because Codex asks for hook approval again whenever anything in a plugin changes. Skill updates leave the markers plugin unchanged, so its hooks keep their approval.
Requires codex CLI.
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_plugins_codex_uninstall.snap b/tests/snapshots/integration__integration_tests__help__help_config_plugins_codex_uninstall.snap
index 7fc8d0af6..3ccbe4ed2 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_plugins_codex_uninstall.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_plugins_codex_uninstall.snap
@@ -45,7 +45,7 @@ info:
success: true
exit_code: 0
----- stdout -----
-wt config plugins codex uninstall - Remove the Worktrunk plugin
+wt config plugins codex uninstall - Remove the Worktrunk plugins
Usage: wt config plugins codex uninstall [OPTIONS]
@@ -69,8 +69,9 @@ Usage: wt config plugins codex uninstall [OPTIONS]
-y, --yes
Skip approval prompts
-Uninstalls the Worktrunk plugin from Codex and removes its marketplace. Equivalent to:
+Uninstalls the Worktrunk plugins from Codex and removes their marketplace. Equivalent to:
+  codex plugin remove worktrunk-markers@worktrunk
  codex plugin remove worktrunk@worktrunk
  codex plugin marketplace remove worktrunk