Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
feat(plugin): ship Codex-native activity hooks (#3364)
Worktrunk Bot512a94de2f5b
diff --git a/docs/content/claude-code.md b/docs/content/claude-code.mdindex 53944bc58..17b07a10e 100644--- a/docs/content/claude-code.md+++ b/docs/content/claude-code.md@@ -12,11 +12,11 @@ Worktrunk ships a plugin for each supported agent CLI. What a plugin provides de| Capability | Claude Code | Codex | OpenCode | Gemini CLI ||---|:-:|:-:|:-:|:-:|| Configuration skill | ✓ | ✓ | | ✓ |-| Activity tracking (🤖/💬 in `wt list`) | ✓ | | ✓ | ✓ |+| Activity tracking (🤖/💬 in `wt list`) | ✓ | ✓ | ✓ | ✓ || Worktree isolation | ✓ | | | || `/wt-switch-create` command | ✓ | | | |-The configuration skill is documentation the agent reads to help set up LLM commits, hooks, and troubleshooting. Activity tracking shows which worktrees have running sessions. Worktree isolation needs worktree-lifecycle hooks and `/wt-switch-create` needs session working-directory switching — both Claude Code-only, so Codex, OpenCode, and Gemini users invoke `wt switch --create` and `wt remove` directly. Codex omits activity tracking because its hooks have no turn-end event, so a 🤖 marker could never clear back to 💬.+The configuration skill is documentation the agent reads to help set up LLM commits, hooks, and troubleshooting. Activity tracking shows which worktrees have running sessions. Worktree isolation needs worktree-lifecycle hooks and `/wt-switch-create` needs session working-directory switching — both Claude Code-only, so Codex, OpenCode, and Gemini users invoke `wt switch --create` and `wt remove` directly. Codex tracks activity through its own turn-end (`Stop`) hook, but has no session-exit event, so a marker persists after a Codex session ends until the next session or a manual `wt config state marker clear`.## Installation@@ -63,7 +63,7 @@ Claude Code is designed to load the skill automatically when it detects worktrun## Activity tracking-The Claude Code, OpenCode, and Gemini plugins track agent sessions with status markers in `wt list`:+The Claude Code, Codex, OpenCode, and Gemini plugins track agent sessions with status markers in `wt list`:<!-- ⚠️ AUTO-GENERATED from tests/snapshots/integration__integration_tests__list__list_with_user_marker.snap — edit source to update -->@@ -83,7 +83,7 @@ The Claude Code, OpenCode, and Gemini plugins track agent sessions with status m- 🤖 — agent is working- 💬 — agent is waiting or idle-The plugin clears the marker when a session ends. A stale marker can remain if the agent process is killed before its session-end hook runs; `wt config state marker clear` removes a marker manually.+The Claude Code, OpenCode, and Gemini plugins clear the marker when a session ends. A stale marker can remain if the agent process is killed before its session-end hook runs. Codex exposes no session-exit event, so its marker always persists after a session ends. In every case, `wt config state marker clear` removes a marker manually.### Manual status markersdiff --git a/plugins/worktrunk/.codex-plugin/plugin.json b/plugins/worktrunk/.codex-plugin/plugin.jsonindex b48c1ee05..555820d1e 100644--- a/plugins/worktrunk/.codex-plugin/plugin.json+++ b/plugins/worktrunk/.codex-plugin/plugin.json@@ -9,6 +9,41 @@"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"+ }+ ]+ }+ ],+ "PermissionRequest": [+ {+ "matcher": "",+ "hooks": [+ {+ "type": "command",+ "command": "bash \"$PLUGIN_ROOT/hooks/wt.sh\" config state marker set 💬 || true"+ }+ ]+ }+ ],+ "Stop": [+ {+ "hooks": [+ {+ "type": "command",+ "command": "bash \"$PLUGIN_ROOT/hooks/wt.sh\" config state marker set 💬 || true"+ }+ ]+ }+ ]+ }+ },"skills": "./skills/","interface": {"displayName": "Worktrunk",diff --git a/plugins/worktrunk/CLAUDE.md b/plugins/worktrunk/CLAUDE.mdindex 09489c34f..4314ae25d 100644--- a/plugins/worktrunk/CLAUDE.md+++ b/plugins/worktrunk/CLAUDE.md@@ -20,13 +20,15 @@ worktrunk/ ← repo root = marketplace root│ 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 ← canonical hook shim; Claude/Codex reach it via- │ $CLAUDE_PLUGIN_ROOT, Gemini via+ ├── hooks/wt.sh ← canonical hook shim; Claude reaches it via+ │ $CLAUDE_PLUGIN_ROOT, Codex via $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 Known Limitations below)+ └── (Codex activity hooks live *inline* in .codex-plugin/plugin.json's+ `hooks` key — see Known Limitations below)```Path resolution differs by tool, all verified end-to-end against the real CLIs:@@ -65,11 +67,20 @@ The 💬 transitions overlap deliberately: `Notification` covers the documented**Tracking**: [claude-code#9516](https://github.com/anthropics/claude-code/issues/9516)-### Codex ships no activity hooks+### Codex activity hooks (marker persists after session end)-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.+The Claude manifest carries `hooks: "./hooks/hooks.json"` (a path); the Codex manifest carries `hooks` as an **inline object**, `{ "hooks": { … } }`, embedding a Codex-tailored hooks file directly. The distinction is deliberate:-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.+- **Why inline, not a path or an absent key.** Claude and Codex share one payload dir. If the Codex manifest omitted `hooks`, Codex would auto-discover `hooks/hooks.json` from the plugin root by convention (`DEFAULT_HOOKS_CONFIG_FILE`, the `None` branch of `load_plugin_hooks`) and surface Worktrunk's *Claude* events in a Codex session ([#3362](https://github.com/max-sixty/worktrunk/issues/3362)). An inline object takes Codex's `Some(Inline)` branch (`resolve_manifest_hooks` in `codex-rs/core-plugins/src/manifest.rs`), which overrides discovery — so the shared Claude file is never loaded and only these Codex-native events fire. Inline keeps the definition self-contained and avoids a second file that could collide with `hooks/hooks.json`.+- **Why `$PLUGIN_ROOT`, not `$CLAUDE_PLUGIN_ROOT`.** Codex exports both to hook commands (`PLUGIN_ROOT` native, `CLAUDE_PLUGIN_ROOT` as an OOTB-compat alias — `codex-rs/hooks/src/engine/discovery.rs`). The Codex file uses the native `$PLUGIN_ROOT` so nothing Claude-branded appears in a Codex session.++The events (Codex's `HookEventsToml` vocabulary, verified against `codex-rs/config/src/hook_config.rs`):+- `UserPromptSubmit` → 🤖 (working)+- `PermissionRequest`, `Stop` → 💬 (waiting for input)++`Stop` fires at turn-end (Codex added it after codex-cli 0.130.0, which had no turn-end event), so 🤖 correctly returns to 💬 when a turn completes — the transition the earlier "no turn-end event" limitation lacked.++**Limitation — marker persists after the session ends.** Codex's `HookEventsToml` has **no `SessionEnd`/session-exit event**, so there is no hook to *clear* the marker when a Codex session exits. The resting state after a normal exit is 💬 (set by the last `Stop`), which reads as "waiting for input" and lingers until the next session or a manual `wt config state marker clear`. This is the same class of limitation already documented above for Claude ("Status persists after user interrupt") — an accepted tradeoff, not a regression. If Codex later adds a session-exit event, add a `marker clear` handler for it here.### Accepted tradeoff: shared `skills/` exposes `wt-switch-create`diff --git a/skills/worktrunk/reference/claude-code.md b/skills/worktrunk/reference/claude-code.mdindex cabd1ddf5..955ad72a9 100644--- a/skills/worktrunk/reference/claude-code.md+++ b/skills/worktrunk/reference/claude-code.md@@ -5,11 +5,11 @@ Worktrunk ships a plugin for each supported agent CLI. What a plugin provides de| Capability | Claude Code | Codex | OpenCode | Gemini CLI ||---|:-:|:-:|:-:|:-:|| Configuration skill | ✓ | ✓ | | ✓ |-| Activity tracking (🤖/💬 in `wt list`) | ✓ | | ✓ | ✓ |+| Activity tracking (🤖/💬 in `wt list`) | ✓ | ✓ | ✓ | ✓ || Worktree isolation | ✓ | | | || `/wt-switch-create` command | ✓ | | | |-The configuration skill is documentation the agent reads to help set up LLM commits, hooks, and troubleshooting. Activity tracking shows which worktrees have running sessions. Worktree isolation needs worktree-lifecycle hooks and `/wt-switch-create` needs session working-directory switching — both Claude Code-only, so Codex, OpenCode, and Gemini users invoke `wt switch --create` and `wt remove` directly. Codex omits activity tracking because its hooks have no turn-end event, so a 🤖 marker could never clear back to 💬.+The configuration skill is documentation the agent reads to help set up LLM commits, hooks, and troubleshooting. Activity tracking shows which worktrees have running sessions. Worktree isolation needs worktree-lifecycle hooks and `/wt-switch-create` needs session working-directory switching — both Claude Code-only, so Codex, OpenCode, and Gemini users invoke `wt switch --create` and `wt remove` directly. Codex tracks activity through its own turn-end (`Stop`) hook, but has no session-exit event, so a marker persists after a Codex session ends until the next session or a manual `wt config state marker clear`.## Installation@@ -69,7 +69,7 @@ Claude Code is designed to load the skill automatically when it detects worktrun## Activity tracking-The Claude Code, OpenCode, and Gemini plugins track agent sessions with status markers in `wt list`:+The Claude Code, Codex, OpenCode, and Gemini plugins track agent sessions with status markers in `wt list`:```bash$ wt list@@ -85,7 +85,7 @@ $ wt list- 🤖 — agent is working- 💬 — agent is waiting or idle-The plugin clears the marker when a session ends. A stale marker can remain if the agent process is killed before its session-end hook runs; `wt config state marker clear` removes a marker manually.+The Claude Code, OpenCode, and Gemini plugins clear the marker when a session ends. A stale marker can remain if the agent process is killed before its session-end hook runs. Codex exposes no session-exit event, so its marker always persists after a session ends. In every case, `wt config state marker clear` removes a marker manually.### Manual status markersdiff --git a/src/cli/config.rs b/src/cli/config.rsindex 5dc50b27e..fa471bb2e 100644--- a/src/cli/config.rs+++ b/src/cli/config.rs@@ -305,7 +305,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. Activity markers in `wt list` are Claude Code only: Codex exposes no turn-end hook event, so the Codex plugin omits them until it does.+ 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. Codex has no session-exit event, so a marker persists after a session ends.## Examplesdiff --git a/src/commands/config/codex.rs b/src/commands/config/codex.rsindex 90eaabbc0..0ce971aa3 100644--- a/src/commands/config/codex.rs+++ b/src/commands/config/codex.rs@@ -44,11 +44,17 @@ pub fn handle_codex_install(yes: bool) -> Result<()> {"{}",hint_message("Next, run /plugins in Codex and install Worktrunk from the marketplace"));- // The Codex plugin deliberately ships no activity-marker hooks: Codex's- // HookEventNameWire vocabulary (codex-cli 0.130.0) has no `Stop`/turn-end- // event, so a 🤖 set on UserPromptSubmit could never return to 💬 within a- // session. Re-add the hooks (and restore the marker hints + docs) once- // Codex exposes a turn-end hook event. See CLAUDE.md → "Plugin Layout".+ // The Codex plugin ships activity-marker hooks inline in its manifest+ // (`hooks` key in .codex-plugin/plugin.json), using Codex's native `Stop`+ // turn-end event to return 🤖 → 💬. Codex has no session-exit event, so the+ // marker persists after a session ends (documented tradeoff). See CLAUDE.md+ // → "Plugin Layout".+ eprintln!(+ "{}",+ hint_message(cformat!(+ "Activity markers appear in <underline>wt list</> once a Codex session runs"+ ))+ );Ok(())}diff --git a/tests/integration_tests/config_show.rs b/tests/integration_tests/config_show.rsindex 357d5c383..f44dd7996 100644--- a/tests/integration_tests/config_show.rs+++ b/tests/integration_tests/config_show.rs@@ -3847,14 +3847,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 no activity-marker hooks: Codex's- // HookEventNameWire vocabulary (codex-cli 0.130.0) has no `Stop`/turn-end- // event, so a 🤖 set on UserPromptSubmit could never return to 💬 within a- // session. Keep the Codex manifest free of a `hooks` key, and its wrapper- // dir manifest-only, until Codex adds a turn-end hook event — see CLAUDE.md- // → "Plugin Layout". (plugins/worktrunk/hooks/ exists post-consolidation,- // but it is the *Claude* plugin's — Codex's manifest never references it.)- assert_eq!(plugin.get("hooks"), None);+ // The Codex plugin ships activity-marker hooks *inline* in its manifest+ // (`hooks` object, not a path). This is deliberate: an absent `hooks` key+ // makes Codex auto-discover the shared `hooks/hooks.json` (which is the+ // *Claude* plugin's) and surface Claude-branded events in a Codex session+ // (#3362). An inline object takes Codex's `Some(Inline)` branch, overriding+ // discovery so only these Codex-native events fire. Codex added a `Stop`+ // turn-end event (post codex-cli 0.130.0), so 🤖 returns to 💬 at turn end.+ // See CLAUDE.md → "Plugin Layout".+ let codex_hooks = plugin+ .get("hooks")+ .and_then(|h| h.get("hooks"))+ .expect("Codex manifest must carry an inline `hooks` object");+ // Exactly the Codex-native events — no `Notification`/`SessionEnd`/+ // `WorktreeCreate`/`WorktreeRemove`, which are Claude-only and would be+ // silently dropped by Codex.+ for event in ["UserPromptSubmit", "PermissionRequest", "Stop"] {+ assert!(+ codex_hooks.get(event).is_some(),+ "Codex hooks must define the {event} event"+ );+ }+ // Commands use Codex's native `$PLUGIN_ROOT`, never the Claude-branded+ // `$CLAUDE_PLUGIN_ROOT` compat alias — nothing Claude-branded in a Codex+ // session (#3362).+ let hooks_json = serde_json::to_string(codex_hooks).unwrap();+ assert!(+ hooks_json.contains("$PLUGIN_ROOT/hooks/wt.sh"),+ "Codex hook commands must call the shim via $PLUGIN_ROOT"+ );+ assert!(+ !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 to collide with the Claude `hooks/hooks.json`.assert!(!project_root.join("plugins/worktrunk/.codex-plugin/hooks")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.snapindex 51146a953..b6370080f 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@@ -10,6 +10,7 @@ info:- "--yes"env:APPDATA: "[TEST_CONFIG_HOME]"+ CLAUDE_CONFIG_DIR: "[TEST_CLAUDE_CONFIG]"CLICOLOR_FORCE: "1"COLUMNS: "500"GIT_AUTHOR_DATE: "2025-01-01T00:00:00Z"@@ -52,3 +53,4 @@ exit_code: 0[36m◎[39m [36mAdding Codex plugin marketplace...[39m[32m✓[39m [32mCodex marketplace configured[39m[2m↳[22m [2mNext, run /plugins in Codex and install Worktrunk from the marketplace[22m+[2m↳[22m [2mActivity markers appear in [4mwt list[24m once a Codex session runs[22mdiff --git a/tests/snapshots/integration__integration_tests__help__help_config_plugins_codex.snap b/tests/snapshots/integration__integration_tests__help__help_config_plugins_codex.snapindex 0edccb45f..2cf1691ff 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@@ -62,7 +62,7 @@ Usage: [1m[36mwt config plugins codex[0m [36m[OPTIONS][0m [36m<COMMAND>[0[1m[36m-y[0m, [1m[36m--yes[0mSkip approval prompts-Bundles a configuration skill — documentation Codex can read to help set up LLM commits, project hooks, and worktree paths. Activity markers in [2mwt list[0m are Claude Code only: Codex exposes no turn-end hook event, so the Codex plugin omits them until it does.+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 [2mwt list[0m while a Codex session runs. Codex has no session-exit event, so a marker persists after a session ends.[1m[32mExamples[0m