Skip to content

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.md
index 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 markers
diff --git a/plugins/worktrunk/.codex-plugin/plugin.json b/plugins/worktrunk/.codex-plugin/plugin.json
index 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.md
index 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.md
index 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 markers
diff --git a/src/cli/config.rs b/src/cli/config.rs
index 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.
## Examples
diff --git a/src/commands/config/codex.rs b/src/commands/config/codex.rs
index 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.rs
index 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.snap
index 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
◎ Adding Codex plugin marketplace...
✓ Codex marketplace configured
↳ Next, run /plugins in Codex and install Worktrunk from the marketplace
+↳ Activity markers appear in wt list once a Codex session runs
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 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: 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. 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.
+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.
Examples