Skip to content

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

refactor(plugins): consolidate Claude + Codex into one payload dir (#2789)

Maximilian Roosd22917702ea7
diff --git a/.claude-plugin/CLAUDE.md b/.claude-plugin/CLAUDE.md
deleted file mode 100644
index d0c761d66..000000000
--- a/.claude-plugin/CLAUDE.md
+++ /dev/null
@@ -1,32 +0,0 @@
-# Claude Code Plugin Guidelines
-
-## Directory Layout
-
-Skills are at the repo root (`skills/`) — the standard plugin location. Hooks
-remain in `.claude-plugin/hooks/` for now.
-
-```
-worktrunk/ ← plugin root (repo root)
-├── .claude-plugin/
-│ ├── plugin.json ← manifest (lists every skill dir)
-│ └── hooks/hooks.json ← activity tracking + WorktreeCreate/Remove hooks
-└── skills/
- ├── worktrunk/ ← config/hook guidance skill + reference docs
- └── wt-switch-create/ ← /wt-switch-create slash command
-```
-
-Paths in `plugin.json` and `marketplace.json` resolve from the plugin root (repo
-root). Each skill directory must be listed in `plugin.json`'s `skills` array.
-
-## Known Limitations
-
-### Status persists after user interrupt
-
-The hooks track Claude Code activity via git config (`worktrunk.status.{branch}`):
-- `UserPromptSubmit` → 🤖 (working)
-- `Notification` → 💬 (waiting for input)
-- `SessionEnd` → clears status
-
-**Problem**: If the user interrupts Claude Code (Escape/Ctrl+C), the 🤖 status persists because there's no `UserInterrupt` hook. The `Stop` hook explicitly does not fire on user interrupt.
-
-**Tracking**: [claude-code#9516](https://github.com/anthropics/claude-code/issues/9516)
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index afa4540c4..b47360f33 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -11,7 +11,7 @@
{
"name": "worktrunk",
"description": "Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows. This plugin provides configuration guidance (LLM commit messages, project hooks, worktree paths) and automatic activity tracking (🤖/💬 indicators in `wt list` showing active Claude sessions).",
- "source": "./"
+ "source": "./plugins/worktrunk"
}
]
}
diff --git a/CLAUDE.md b/CLAUDE.md
index 07ae474c6..3f417ed65 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -168,21 +168,13 @@ cargo insta test --accept -- --test integration "test_help"
Config docs (`USER_CONFIG_START`/`PROJECT_CONFIG_START` sections in `src/cli/mod.rs`) generate `dev/*.example.toml` files where every line is commented out with `#`. TOML comments inside code blocks become double-commented (`# # comment`). Use plain text descriptions ending with colons before each code block instead — inline end-of-line comments (e.g., `key = "value" # explanation`) are fine.
-## Codex Plugin
+## Plugin Layout
-The Codex plugin is separate from the Claude Code plugin (`.claude-plugin/`) and uses Codex's marketplace 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.
-```
-.agents/plugins/marketplace.json ← marketplace manifest Codex enumerates
-plugins/worktrunk/.codex-plugin/plugin.json ← plugin manifest
-plugins/worktrunk/skills -> ../../skills ← symlink to repo-root skills/
-```
-
-Codex discovers a marketplace's plugin list strictly from `<repo-root>/.agents/plugins/marketplace.json` (no fallback to `.claude-plugin/marketplace.json`). Each plugin's `source` must be an object pointing at a non-empty subdirectory — codex rejects a bare or root-relative source — so the plugin lives in `plugins/worktrunk/`, not at the repo root.
-
-**No activity-marker hooks.** Unlike the Claude Code plugin, the Codex plugin ships no `hooks` — the manifest has no `hooks` key and there is no `hooks/` directory. 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 💬 within a session — it would stick at "working" indefinitely. Re-add `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.
+**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`.** The manifest's `"skills": "./skills/"` resolves through the `plugins/worktrunk/skills -> ../../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. Don't add a Codex-only skills subtree to exclude it.
+**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.
## Data Safety
diff --git a/plugins/worktrunk/CLAUDE.md b/plugins/worktrunk/CLAUDE.md
new file mode 100644
index 000000000..fdb03b011
--- /dev/null
+++ b/plugins/worktrunk/CLAUDE.md
@@ -0,0 +1,57 @@
+# Worktrunk Plugin Guidelines (Claude Code + Codex)
+
+## 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.
+
+```
+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)
+ ├── 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
+ ├── 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:
+
+- **Claude**: `.claude-plugin/marketplace.json` `source: "./plugins/worktrunk"`.
+ Claude reads `plugins/worktrunk/plugin.json` (at the plugin root, *not* a
+ `.claude-plugin/` subdir). `hooks` and `skills` paths in `plugin.json` resolve
+ from the plugin root, so `./skills/worktrunk` follows the `skills` symlink to
+ the repo-root `skills/worktrunk`. `${CLAUDE_PLUGIN_ROOT}` is the plugin root.
+- **Codex**: `.agents/plugins/marketplace.json` `source` object
+ `{ "source": "local", "path": "./plugins/worktrunk" }`. Codex reads
+ `plugins/worktrunk/.codex-plugin/plugin.json`. `skills: "./skills/"` resolves
+ through the same symlink.
+
+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").
+
+## Known Limitations
+
+### Status persists after user interrupt (Claude)
+
+The Claude hooks track activity via git config (`worktrunk.status.{branch}`):
+- `UserPromptSubmit` → 🤖 (working)
+- `Notification` → 💬 (waiting for input)
+- `SessionEnd` → clears status
+
+**Problem**: If the user interrupts Claude Code (Escape/Ctrl+C), the 🤖 status persists because there's no `UserInterrupt` hook. The `Stop` hook explicitly does not fire on user interrupt.
+
+**Tracking**: [claude-code#9516](https://github.com/anthropics/claude-code/issues/9516)
+
+### Codex ships no activity hooks
+
+Codex-cli 0.130.0's hook event vocabulary has no `Stop`/turn-end event, so a 🤖 marker could never return to 💬. The Codex manifest deliberately carries no `hooks` key. See repo CLAUDE.md → "Plugin Layout" for the re-enablement conditions.
diff --git a/.claude-plugin/README.md b/plugins/worktrunk/README.md
similarity index 100%
rename from .claude-plugin/README.md
rename to plugins/worktrunk/README.md
diff --git a/.claude-plugin/hooks/hooks.json b/plugins/worktrunk/hooks/hooks.json
similarity index 61%
rename from .claude-plugin/hooks/hooks.json
rename to plugins/worktrunk/hooks/hooks.json
index 34aa705f9..9eb033da4 100644
--- a/.claude-plugin/hooks/hooks.json
+++ b/plugins/worktrunk/hooks/hooks.json
@@ -5,7 +5,7 @@
"hooks": [
{
"type": "command",
- "command": "bash \"${CLAUDE_PLUGIN_ROOT}/.claude-plugin/hooks/wt.sh\" config state marker set 🤖 || true"
+ "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/wt.sh\" config state marker set 🤖 || true"
}
]
}
@@ -16,7 +16,7 @@
"hooks": [
{
"type": "command",
- "command": "bash \"${CLAUDE_PLUGIN_ROOT}/.claude-plugin/hooks/wt.sh\" config state marker set 💬 || true"
+ "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/wt.sh\" config state marker set 💬 || true"
}
]
}
@@ -27,7 +27,7 @@
"hooks": [
{
"type": "command",
- "command": "bash \"${CLAUDE_PLUGIN_ROOT}/.claude-plugin/hooks/wt.sh\" config state marker clear || true"
+ "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/wt.sh\" config state marker clear || true"
}
]
}
@@ -37,7 +37,7 @@
"hooks": [
{
"type": "command",
- "command": "jq -r '.name' | xargs -I{} bash \"${CLAUDE_PLUGIN_ROOT}/.claude-plugin/hooks/wt.sh\" switch --create {} --no-cd --format=json | jq -r '.path'"
+ "command": "jq -r '.name' | xargs -I{} bash \"${CLAUDE_PLUGIN_ROOT}/hooks/wt.sh\" switch --create {} --no-cd --format=json | jq -r '.path'"
}
]
}
@@ -47,7 +47,7 @@
"hooks": [
{
"type": "command",
- "command": "jq -r '.worktree_path' | xargs bash \"${CLAUDE_PLUGIN_ROOT}/.claude-plugin/hooks/wt.sh\" remove -D --foreground"
+ "command": "jq -r '.worktree_path' | xargs bash \"${CLAUDE_PLUGIN_ROOT}/hooks/wt.sh\" remove -D --foreground"
}
]
}
diff --git a/.claude-plugin/hooks/wt.sh b/plugins/worktrunk/hooks/wt.sh
similarity index 100%
rename from .claude-plugin/hooks/wt.sh
rename to plugins/worktrunk/hooks/wt.sh
diff --git a/.claude-plugin/plugin.json b/plugins/worktrunk/plugin.json
similarity index 90%
rename from .claude-plugin/plugin.json
rename to plugins/worktrunk/plugin.json
index 88b68f0e2..9c74683d7 100644
--- a/.claude-plugin/plugin.json
+++ b/plugins/worktrunk/plugin.json
@@ -4,7 +4,7 @@
"author": {
"name": "Worktrunk"
},
- "hooks": "./.claude-plugin/hooks/hooks.json",
+ "hooks": "./hooks/hooks.json",
"skills": [
"./skills/worktrunk",
"./skills/wt-switch-create"
diff --git a/src/commands/config/codex.rs b/src/commands/config/codex.rs
index d07b748a2..90eaabbc0 100644
--- a/src/commands/config/codex.rs
+++ b/src/commands/config/codex.rs
@@ -48,7 +48,7 @@ pub fn handle_codex_install(yes: bool) -> Result<()> {
// 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 → "Codex Plugin".
+ // Codex exposes a turn-end hook event. See CLAUDE.md → "Plugin Layout".
Ok(())
}
diff --git a/tests/integration_tests/config_show.rs b/tests/integration_tests/config_show.rs
index d86a70082..67acbfd38 100644
--- a/tests/integration_tests/config_show.rs
+++ b/tests/integration_tests/config_show.rs
@@ -3588,13 +3588,16 @@ fn test_codex_plugin_metadata_is_valid_json() {
// 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 manifest free of a `hooks` key (and the hooks/ dir
- // absent) until Codex adds a turn-end hook event — see CLAUDE.md →
- // "Codex Plugin".
+ // 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);
assert!(
- !project_root.join("plugins/worktrunk/hooks").exists(),
- "plugins/worktrunk/hooks/ must not exist while Codex lacks a turn-end hook event"
+ !project_root
+ .join("plugins/worktrunk/.codex-plugin/hooks")
+ .exists(),
+ "the Codex wrapper dir must hold only plugin.json"
);
assert_eq!(marketplace["plugins"][0]["name"], "worktrunk");
// Source is a non-empty subdir object; a bare "./" is rejected by codex.
@@ -3612,6 +3615,50 @@ 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.
+#[test]
+fn test_plugin_layout_is_consolidated() {
+ let root = std::path::Path::new(env!("CARGO_MANIFEST_DIR"));
+ let read = |p: &str| fs::read_to_string(root.join(p)).unwrap();
+ let json = |p: &str| serde_json::from_str::<serde_json::Value>(&read(p)).unwrap();
+
+ // Repo root keeps ONLY the two loader-mandated marketplace pointers.
+ assert!(
+ !root.join(".claude-plugin/plugin.json").exists()
+ && !root.join(".claude-plugin/hooks").exists(),
+ ".claude-plugin/ at the repo root must hold only marketplace.json"
+ );
+ let claude_mkt = json(".claude-plugin/marketplace.json");
+ assert_eq!(claude_mkt["plugins"][0]["source"], "./plugins/worktrunk");
+
+ // Claude manifest at the plugin root (no wrapper); hooks relative to it.
+ let claude = json("plugins/worktrunk/plugin.json");
+ assert_eq!(claude["hooks"], "./hooks/hooks.json");
+ assert!(
+ root.join("plugins/worktrunk/hooks/hooks.json").exists()
+ && root.join("plugins/worktrunk/hooks/wt.sh").exists(),
+ "Claude hooks must live at the plugin root's hooks/"
+ );
+ assert!(
+ !read("plugins/worktrunk/hooks/hooks.json").contains(".claude-plugin/hooks/"),
+ "hooks.json must reference ${{CLAUDE_PLUGIN_ROOT}}/hooks/wt.sh, not the old wrapper path"
+ );
+
+ // The description is duplicated across the Claude marketplace pointer and
+ // the Claude manifest — they must stay byte-identical.
+ assert_eq!(
+ claude_mkt["plugins"][0]["description"], claude["description"],
+ ".claude-plugin/marketplace.json and plugins/worktrunk/plugin.json descriptions drifted"
+ );
+}
+
// ==================== Plugin Install-Statusline Tests ====================
#[rstest]