hookmux 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (65) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +402 -2
  3. package/dist/chunks/add-ZWGK62EX.mjs +1 -0
  4. package/dist/chunks/chunk-2ZCM3JZR.mjs +3 -0
  5. package/dist/chunks/chunk-5GQP3BA6.mjs +1 -0
  6. package/dist/chunks/chunk-65XA3RK3.mjs +4 -0
  7. package/dist/chunks/chunk-6GL55FEQ.mjs +20 -0
  8. package/dist/chunks/chunk-7Z3AMI24.mjs +1 -0
  9. package/dist/chunks/chunk-AHPMRYYF.mjs +1 -0
  10. package/dist/chunks/chunk-BF25CRHJ.mjs +1 -0
  11. package/dist/chunks/chunk-CA2GWCFP.mjs +3 -0
  12. package/dist/chunks/chunk-CSXS5D2F.mjs +1 -0
  13. package/dist/chunks/chunk-CZY5UAXM.mjs +1 -0
  14. package/dist/chunks/chunk-DJHE642J.mjs +7 -0
  15. package/dist/chunks/chunk-DZU2NMID.mjs +1 -0
  16. package/dist/chunks/chunk-F3USS665.mjs +1 -0
  17. package/dist/chunks/chunk-FF55QGCZ.mjs +1 -0
  18. package/dist/chunks/chunk-G6SJQTFF.mjs +1 -0
  19. package/dist/chunks/chunk-IAGBX723.mjs +2 -0
  20. package/dist/chunks/chunk-IJHUIMJA.mjs +5 -0
  21. package/dist/chunks/chunk-K73ZPBFM.mjs +45 -0
  22. package/dist/chunks/chunk-L3BSVLQG.mjs +1 -0
  23. package/dist/chunks/chunk-OMKE4U3M.mjs +1 -0
  24. package/dist/chunks/chunk-OXHAGFXG.mjs +12 -0
  25. package/dist/chunks/chunk-OYGOSD6V.mjs +1 -0
  26. package/dist/chunks/chunk-QTY23VNU.mjs +1 -0
  27. package/dist/chunks/chunk-RG3EOP4J.mjs +1 -0
  28. package/dist/chunks/chunk-SXIEWTYT.mjs +1 -0
  29. package/dist/chunks/chunk-UERSXYXZ.mjs +3 -0
  30. package/dist/chunks/chunk-WZSNBZ6D.mjs +2 -0
  31. package/dist/chunks/chunk-XPLEWNGF.mjs +1 -0
  32. package/dist/chunks/chunk-ZDCAHPWY.mjs +2 -0
  33. package/dist/chunks/chunk-ZNEBE4WO.mjs +1 -0
  34. package/dist/chunks/disable-KRHQYUQU.mjs +3 -0
  35. package/dist/chunks/doctor-KERAJBFA.mjs +7 -0
  36. package/dist/chunks/enable-SWA7C4K2.mjs +4 -0
  37. package/dist/chunks/explain-WNQLELTA.mjs +9 -0
  38. package/dist/chunks/hook-main-PW67WMNF.mjs +1 -0
  39. package/dist/chunks/init-46THKH7Z.mjs +12 -0
  40. package/dist/chunks/install-J4QGOOCD.mjs +15 -0
  41. package/dist/chunks/list-NAFC2CUM.mjs +5 -0
  42. package/dist/chunks/log-ELHUFP5Y.mjs +11 -0
  43. package/dist/chunks/new-UASRUAP2.mjs +186 -0
  44. package/dist/chunks/promote-4RJUMW7Y.mjs +24 -0
  45. package/dist/chunks/registry-P6V5HZQN.mjs +1 -0
  46. package/dist/chunks/remove-XCOCPNJJ.mjs +3 -0
  47. package/dist/chunks/schema-FFOAJAET.mjs +4 -0
  48. package/dist/chunks/sync-UCVS5O2X.mjs +4 -0
  49. package/dist/chunks/test-BCLMCB5A.mjs +8 -0
  50. package/dist/chunks/uninstall-ZMGYPYVA.mjs +7 -0
  51. package/dist/chunks/validate-ICFP6TSC.mjs +1 -0
  52. package/dist/cli.mjs +4 -0
  53. package/dist/hook.mjs +1 -0
  54. package/launcher/hookmux-hook.sh +83 -0
  55. package/launcher/opencode-plugin.js +236 -0
  56. package/package.json +57 -4
  57. package/plugins/hookmux-authoring/plugin.toml +65 -0
  58. package/plugins/hookmux-authoring/tests.toml +119 -0
  59. package/skills/hookmux/SKILL.md +102 -0
  60. package/skills/hookmux/references/check-kinds.md +124 -0
  61. package/skills/hookmux/references/effects.md +24 -0
  62. package/skills/hookmux/references/examples/moodboard/plugin.toml +72 -0
  63. package/skills/hookmux/references/examples/moodboard/tests.toml +20 -0
  64. package/skills/hookmux/references/hosts.md +173 -0
  65. package/skills/hookmux/references/plugin-format.md +400 -0
@@ -0,0 +1,236 @@
1
+ // hookmux generated this opencode plugin; `hookmux sync` rewrites it.
2
+ // Do not edit by hand: the next `hookmux sync` or `hookmux add` overwrites it.
3
+ //
4
+ // opencode has no command hooks, so this file stands in for one: it turns
5
+ // each opencode plugin hook into a hookmux payload, runs the launcher below
6
+ // as a short-lived process, and applies the JSON answer it prints. Every
7
+ // launcher call is wrapped so a crash, a timeout, a non-zero exit or garbage
8
+ // output all count as "no answer" rather than breaking opencode's own turn.
9
+
10
+ import { spawn } from "node:child_process";
11
+ import { randomUUID } from "node:crypto";
12
+
13
+ const LAUNCHER = "@LAUNCHER_JSON@";
14
+ const EVENTS = "@EVENTS_JSON@";
15
+ const TIMEOUT_MS = "@TIMEOUT_MS@";
16
+
17
+ /** opencode's built-in tool ids that hookmux's host adapter also maps; kept here only for the payload's own `tool_name`. */
18
+ const CANONICAL_TOOL_NAMES = {
19
+ bash: "Bash",
20
+ write: "Write",
21
+ edit: "Edit",
22
+ read: "Read",
23
+ apply_patch: "Edit",
24
+ };
25
+
26
+ function newId(prefix) {
27
+ return `${prefix}_hookmux_${randomUUID().replaceAll("-", "")}`;
28
+ }
29
+
30
+ /** Runs the launcher once; resolves the parsed answer, or null for anything that is not a clean, parseable answer. */
31
+ function callHookmux(canonicalEvent, payload) {
32
+ return new Promise((resolve) => {
33
+ let child;
34
+ try {
35
+ child = spawn(LAUNCHER, ["--host", "opencode", "--event", canonicalEvent], { stdio: ["pipe", "pipe", "ignore"] });
36
+ } catch {
37
+ resolve(null);
38
+ return;
39
+ }
40
+ let out = "";
41
+ let settled = false;
42
+ const finish = (value) => {
43
+ if (settled) return;
44
+ settled = true;
45
+ resolve(value);
46
+ };
47
+ // Decoded as text so a multi-byte character split across chunks is not garbled.
48
+ child.stdout.setEncoding("utf8");
49
+ // A launcher that exits without reading stdin (no engine installed yet) makes the
50
+ // write below fail with EPIPE; unhandled, that stream error would crash opencode.
51
+ child.stdin.on("error", () => {});
52
+ const timer = setTimeout(() => {
53
+ child.kill("SIGKILL");
54
+ finish(null);
55
+ }, TIMEOUT_MS);
56
+ child.stdout.on("data", (chunk) => {
57
+ out += chunk;
58
+ });
59
+ child.on("error", () => {
60
+ clearTimeout(timer);
61
+ finish(null);
62
+ });
63
+ child.on("close", (code) => {
64
+ clearTimeout(timer);
65
+ if (code !== 0 || out.trim() === "") {
66
+ finish(null);
67
+ return;
68
+ }
69
+ try {
70
+ finish(JSON.parse(out));
71
+ } catch {
72
+ finish(null);
73
+ }
74
+ });
75
+ try {
76
+ child.stdin.write(JSON.stringify(payload));
77
+ child.stdin.end();
78
+ } catch {
79
+ finish(null);
80
+ }
81
+ });
82
+ }
83
+
84
+ async function toast(client, message) {
85
+ if (!client?.tui?.showToast) return;
86
+ try {
87
+ await client.tui.showToast({ body: { message, variant: "info" } });
88
+ } catch {
89
+ // No user-visible route for this notice; dropping it still keeps the turn going.
90
+ }
91
+ }
92
+
93
+ function pushSyntheticText(output, sessionID, messageID, text) {
94
+ output.parts.push({ id: newId("prt"), sessionID, messageID, type: "text", text, synthetic: true });
95
+ }
96
+
97
+ function contextOf(answer) {
98
+ return answer && typeof answer.context === "string" && answer.context ? answer.context : null;
99
+ }
100
+
101
+ /**
102
+ * `session.created`, read through the generic `event` hook. Records subagent
103
+ * sessions (so their prompts count as the system's) and starts the
104
+ * session.start call. Its context is held for that session's first
105
+ * `chat.message` below, since `event` itself has no output to set.
106
+ */
107
+ function makeSessionCreatedHandler(ctx) {
108
+ return async ({ event }) => {
109
+ try {
110
+ if (event?.type !== "session.created") return;
111
+ const info = event.properties?.info;
112
+ if (!info?.id) return;
113
+ if (info.parentID) ctx.subagentSessions.add(info.id);
114
+ if (!EVENTS.includes("session.start")) return;
115
+ const pending = callHookmux("session.start", {
116
+ session_id: info.id,
117
+ cwd: ctx.directory,
118
+ hook_event_name: "event",
119
+ origin: info.parentID ? "system" : "user",
120
+ });
121
+ // Stored before the first await: opencode runs this hook synchronously when it
122
+ // publishes session.created (core/src/event.ts notify), so the entry exists before
123
+ // the session's first chat.message even when the answer arrives later.
124
+ ctx.pendingContext.set(info.id, pending.then(contextOf));
125
+ const answer = await pending;
126
+ if (answer && typeof answer.notice === "string" && answer.notice) await toast(ctx.client, answer.notice);
127
+ } catch {
128
+ // session.created is read-only from hookmux's side; never let it break startup.
129
+ }
130
+ };
131
+ }
132
+
133
+ /** `chat.message`: reads the submitted prompt text and may add a synthetic context part. */
134
+ function makeChatMessageHandler(ctx) {
135
+ return async (hookInput, output) => {
136
+ try {
137
+ const sessionID = hookInput.sessionID;
138
+ // Taken synchronously, so only the session's first chat.message delivers it.
139
+ const sessionStart = ctx.pendingContext.get(sessionID) ?? null;
140
+ ctx.pendingContext.delete(sessionID);
141
+ const messageID = output.message?.id ?? hookInput.messageID ?? newId("msg");
142
+ const prompt = output.parts
143
+ .filter((part) => part?.type === "text" && !part.synthetic && !part.ignored)
144
+ .map((part) => part.text)
145
+ .join("\n\n");
146
+ // Session-start context is still delivered when no plugin listens to prompt.submit.
147
+ const promptAnswer = EVENTS.includes("prompt.submit")
148
+ ? callHookmux("prompt.submit", {
149
+ session_id: sessionID,
150
+ cwd: ctx.directory,
151
+ hook_event_name: "chat.message",
152
+ prompt,
153
+ origin: ctx.subagentSessions.has(sessionID) ? "system" : "user",
154
+ })
155
+ : null;
156
+ const [answer, startContext] = await Promise.all([promptAnswer, sessionStart]);
157
+ if (startContext) pushSyntheticText(output, sessionID, messageID, startContext);
158
+
159
+ if (!answer) return;
160
+ if (typeof answer.context === "string" && answer.context) {
161
+ pushSyntheticText(output, sessionID, messageID, answer.context);
162
+ }
163
+ if (typeof answer.notice === "string" && answer.notice) await toast(ctx.client, answer.notice);
164
+ } catch {
165
+ // Adding context is a bonus for this turn, never a reason to fail the user's prompt.
166
+ }
167
+ };
168
+ }
169
+
170
+ /** `tool.execute.before`: the one hook whose deny must reach opencode as a thrown error. */
171
+ function makeToolBeforeHandler(ctx) {
172
+ return async (hookInput, output) => {
173
+ let answer = null;
174
+ try {
175
+ if (!EVENTS.includes("tool.before")) return;
176
+ answer = await callHookmux("tool.before", {
177
+ session_id: hookInput.sessionID,
178
+ cwd: ctx.directory,
179
+ hook_event_name: "tool.execute.before",
180
+ tool_name: CANONICAL_TOOL_NAMES[hookInput.tool] ?? hookInput.tool,
181
+ tool_input: output.args,
182
+ });
183
+ // Not awaited, so a slow toast can never hold up the tool call or its deny.
184
+ if (answer && typeof answer.notice === "string" && answer.notice) void toast(ctx.client, answer.notice);
185
+ } catch {
186
+ answer = null;
187
+ }
188
+ // Denying is the one effect that must reach opencode as a thrown error,
189
+ // so it stays outside the try/catch above.
190
+ if (answer && typeof answer.block === "string" && answer.block) throw new Error(answer.block);
191
+ };
192
+ }
193
+
194
+ /** `tool.execute.after`: may append context to the tool's own output text. */
195
+ function makeToolAfterHandler(ctx) {
196
+ return async (hookInput, output) => {
197
+ try {
198
+ if (!EVENTS.includes("tool.after")) return;
199
+ const answer = await callHookmux("tool.after", {
200
+ session_id: hookInput.sessionID,
201
+ cwd: ctx.directory,
202
+ hook_event_name: "tool.execute.after",
203
+ tool_name: CANONICAL_TOOL_NAMES[hookInput.tool] ?? hookInput.tool,
204
+ tool_input: hookInput.args,
205
+ tool_response: output.output,
206
+ });
207
+ if (!answer) return;
208
+ if (typeof answer.notice === "string" && answer.notice) await toast(ctx.client, answer.notice);
209
+ if (typeof answer.context === "string" && answer.context && typeof output.output === "string") {
210
+ output.output = `${output.output}\n\n${answer.context}`;
211
+ }
212
+ } catch {
213
+ // Appending context after the tool ran is a bonus; the tool result still stands.
214
+ }
215
+ };
216
+ }
217
+
218
+ export default async function hookmuxPlugin(input) {
219
+ const ctx = {
220
+ client: input?.client,
221
+ directory: input?.directory ?? process.cwd(),
222
+ // Subagent session ids (session.created carries parentID for them), so a
223
+ // prompt inside one is marked origin "system" instead of the user's.
224
+ subagentSessions: new Set(),
225
+ // Session id to a promise of the context hookmux returned for session.created
226
+ // (or null), held until that session's first chat.message because the
227
+ // `event` hook has no output.
228
+ pendingContext: new Map(),
229
+ };
230
+ return {
231
+ event: makeSessionCreatedHandler(ctx),
232
+ "chat.message": makeChatMessageHandler(ctx),
233
+ "tool.execute.before": makeToolBeforeHandler(ctx),
234
+ "tool.execute.after": makeToolAfterHandler(ctx),
235
+ };
236
+ }
package/package.json CHANGED
@@ -1,6 +1,59 @@
1
1
  {
2
2
  "name": "hookmux",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "One hook entry for every coding agent: Claude Code, Codex, Gemini CLI, Qwen Code, Factory Droid, Qoder, CodeBuddy and opencode. Write a hook once as a plugin and it runs in all of them.",
5
+ "keywords": [
6
+ "claude-code",
7
+ "codex",
8
+ "gemini-cli",
9
+ "qwen-code",
10
+ "factory-droid",
11
+ "qoder",
12
+ "codebuddy",
13
+ "opencode",
14
+ "hooks",
15
+ "agents",
16
+ "llm"
17
+ ],
18
+ "license": "MIT",
19
+ "author": "khanglvm",
20
+ "repository": {
21
+ "type": "git",
22
+ "url": "git+https://github.com/khanglvm/hookmux.git"
23
+ },
24
+ "homepage": "https://github.com/khanglvm/hookmux#readme",
25
+ "bugs": {
26
+ "url": "https://github.com/khanglvm/hookmux/issues"
27
+ },
28
+ "type": "module",
29
+ "bin": {
30
+ "hookmux": "dist/cli.mjs"
31
+ },
32
+ "files": [
33
+ "dist",
34
+ "launcher",
35
+ "plugins",
36
+ "skills"
37
+ ],
38
+ "engines": {
39
+ "node": ">=22"
40
+ },
41
+ "packageManager": "pnpm@12.15.0",
42
+ "scripts": {
43
+ "build": "pnpm run gen:refs && node scripts/build.ts",
44
+ "gen:refs": "node scripts/gen-skill-refs.ts",
45
+ "smoke": "sh scripts/smoke-launcher.sh",
46
+ "typecheck": "tsc --noEmit",
47
+ "lint": "biome check .",
48
+ "format": "biome check --write .",
49
+ "test": "node --test --test-concurrency=4 --test-reporter=spec \"test/**/*.test.ts\"",
50
+ "check": "pnpm lint && pnpm typecheck && pnpm test && pnpm build"
51
+ },
52
+ "devDependencies": {
53
+ "@biomejs/biome": "2.6.6",
54
+ "@types/node": "22.20.5",
55
+ "esbuild": "0.28.2",
56
+ "smol-toml": "1.9.1",
57
+ "typescript": "7.0.2"
58
+ }
59
+ }
@@ -0,0 +1,65 @@
1
+ # Points the agent at the `hookmux` authoring skill when a prompt asks for an
2
+ # automatic behaviour: an explicit "make a hook" request, or a standing rule
3
+ # such as "whenever I ... remind me". Rules only. Prompts about code hooks
4
+ # (React hooks, git hooks, webhooks) are exempt, because "hook" there means
5
+ # something else.
6
+ schema = 1
7
+ id = "hookmux-authoring"
8
+ version = "1.0.0"
9
+ description = "Suggest the hookmux skill when a prompt asks for a hook or a standing automatic rule."
10
+ events = ["prompt.submit"]
11
+ phase = "route"
12
+ priority = 60
13
+ dedupe = "session"
14
+ when = "(asks_for_hook or standing_rule) and not code_hook and not hook_function_name"
15
+
16
+ # An explicit request to build a hook. "webhook" never matches, because the
17
+ # word before "hook" must be an article, "new" or "hookmux".
18
+ [checks.asks_for_hook]
19
+ kind = "regex"
20
+ patterns = [
21
+ '\b(make|create|add|set ?up|write|build|need|want)\s+(me\s+)?(a|an|one|another|some|new)\s+(new\s+)?(hookmux\s+)?hooks?\b',
22
+ '\bhookmux (hook|plugin)s?\b',
23
+ '(tạo|thêm|viết|làm|cài|thiết lập|dựng)( (một|cái|1))? hook',
24
+ ]
25
+
26
+ # A standing rule, in either order: a "whenever / every time" clause and then
27
+ # an imperative directive ("..., warn me"), or "remind me ... whenever I ...".
28
+ # The order is the signal: "tell me why it fails every time I push" and "why
29
+ # does eslint warn every time I save" are bug reports, not rules. Bare verbs
30
+ # only, so "warns", "warning" and "blocks" never count.
31
+ [checks.standing_rule]
32
+ kind = "regex"
33
+ patterns = [
34
+ '\b(whenever|every ?time|each time|any ?time)\s+(I|you|we)\b[^,.?!]{0,100},\s*(please\s+|then\s+|always\s+)?(remind|warn|block|suggest|alert|notify|nudge|tell me|ask me)\b',
35
+ '\b(remind|warn|alert|notify|nudge) me\b[^.?!]{0,100}\b(whenever|every ?time|each time|any ?time)\s+(I|we)\b',
36
+ '(mỗi (khi|lần)|bất (cứ|kỳ) (khi|lúc) nào|hễ)[^,.?!]{0,100}(,|\sthì)\s*(hãy\s+)?(nhắc|cảnh báo|chặn|gợi ý|đề xuất)',
37
+ '(nhắc|cảnh báo|chặn|gợi ý cho) tôi[^.?!]{0,100}(mỗi (khi|lần)|bất (cứ|kỳ) (khi|lúc) nào)',
38
+ ]
39
+
40
+ # Other meanings of "hook", plus Vietnamese "it shows a warning" bug reports.
41
+ [checks.code_hook]
42
+ kind = "regex"
43
+ patterns = [
44
+ '\breact hooks?\b',
45
+ '\bcustom hooks?\b',
46
+ '\blifecycle hooks?\b',
47
+ '\bhooks? (in|for|of) (react|vue|preact|solid|svelte|angular|wordpress|webpack|vite|pytest)\b',
48
+ '\b(git|pre-?commit|pre-?push|commit-msg|post-?commit|post-?merge|post-?checkout|husky)\s+hooks?\b',
49
+ '\.git/hooks',
50
+ '\b(husky|lefthook)\b',
51
+ '\bwebhooks?\b',
52
+ 'hook react',
53
+ '(hiện|hiển thị|bị|ra|có|nó) cảnh báo',
54
+ ]
55
+
56
+ # React-style hook names (useEffect, useDebounce). Case-sensitive, so "user"
57
+ # and "used" do not match.
58
+ [checks.hook_function_name]
59
+ kind = "regex"
60
+ flags = "u"
61
+ patterns = ['\buse[A-Z][A-Za-z0-9]*']
62
+
63
+ [[then]]
64
+ effect = "inject"
65
+ text = "The user may be asking for an automatic behaviour, which hookmux builds as a plugin. If so, load the `hookmux` skill and follow its workflow. Ignore this when the request is about code hooks (React hooks, git hooks, webhooks) or the skill is already loaded."
@@ -0,0 +1,119 @@
1
+ # Cases for `hookmux test hookmux-authoring`.
2
+
3
+ # Should fire: explicit hook requests and standing rules, English and Vietnamese.
4
+ [[case]]
5
+ prompt = "make a hook that reminds me to update the changelog when I mention a release"
6
+ expect = "fire"
7
+
8
+ [[case]]
9
+ prompt = "Create a hook to block prompts that contain an API key"
10
+ expect = "fire"
11
+
12
+ [[case]]
13
+ prompt = "can you set up a hook so the agent suggests running the tests before a commit?"
14
+ expect = "fire"
15
+
16
+ [[case]]
17
+ prompt = "add a hook that warns me before any git push --force"
18
+ expect = "fire"
19
+
20
+ [[case]]
21
+ prompt = "I want a hook that blocks rm -rf in shell commands"
22
+ expect = "fire"
23
+
24
+ [[case]]
25
+ prompt = "write a hookmux plugin that adds our markdown style guide to the context"
26
+ expect = "fire"
27
+
28
+ [[case]]
29
+ prompt = "whenever I mention production, warn me to double-check the target environment"
30
+ expect = "fire"
31
+
32
+ [[case]]
33
+ prompt = "every time I ask for a database migration, remind me to write the rollback too"
34
+ expect = "fire"
35
+
36
+ [[case]]
37
+ prompt = "tạo hook nhắc tôi chạy test trước khi commit"
38
+ expect = "fire"
39
+
40
+ [[case]]
41
+ prompt = "mỗi khi tôi nhắc đến deploy, hãy cảnh báo tôi kiểm tra môi trường staging"
42
+ expect = "fire"
43
+
44
+ [[case]]
45
+ prompt = "bất cứ khi nào tôi hỏi về cơ sở dữ liệu, hãy gợi ý đọc schema trước"
46
+ expect = "fire"
47
+
48
+ [[case]]
49
+ prompt = "remind me to update the API docs whenever I change an endpoint"
50
+ expect = "fire"
51
+
52
+ [[case]]
53
+ prompt = "nhắc tôi cập nhật tài liệu mỗi khi tôi đổi API"
54
+ expect = "fire"
55
+
56
+ # Should stay silent: code hooks, webhooks and ordinary "every time" sentences.
57
+ [[case]]
58
+ prompt = "write a React hook useDebounce for the search box"
59
+ expect = "silent"
60
+
61
+ [[case]]
62
+ prompt = "this useEffect hook runs every time the component renders, can you fix it?"
63
+ expect = "silent"
64
+
65
+ [[case]]
66
+ prompt = "create a custom hook for form state in React"
67
+ expect = "silent"
68
+
69
+ [[case]]
70
+ prompt = "debug why the git pre-commit hook fails on lint"
71
+ expect = "silent"
72
+
73
+ [[case]]
74
+ prompt = "add a hook to the husky config so lint runs before push"
75
+ expect = "silent"
76
+
77
+ [[case]]
78
+ prompt = "add a webhook handler for Stripe payment events"
79
+ expect = "silent"
80
+
81
+ [[case]]
82
+ prompt = "the webhook endpoint returns 500 every time I resend the event"
83
+ expect = "silent"
84
+
85
+ [[case]]
86
+ prompt = "every time I run the tests on CI they fail with a timeout"
87
+ expect = "silent"
88
+
89
+ [[case]]
90
+ prompt = "every time I open the app I get a warning about cookies"
91
+ expect = "silent"
92
+
93
+ [[case]]
94
+ prompt = "explain how lifecycle hooks work in Vue"
95
+ expect = "silent"
96
+
97
+ [[case]]
98
+ prompt = "tạo hook React useFetch để gọi API"
99
+ expect = "silent"
100
+
101
+ [[case]]
102
+ prompt = "mỗi khi tôi chạy build nó hiện cảnh báo deprecated, sửa giúp tôi"
103
+ expect = "silent"
104
+
105
+ [[case]]
106
+ prompt = "tell me why the build fails every time I push"
107
+ expect = "silent"
108
+
109
+ [[case]]
110
+ prompt = "can you suggest a fix? it crashes every time I open settings"
111
+ expect = "silent"
112
+
113
+ [[case]]
114
+ prompt = "why does eslint warn every time I save"
115
+ expect = "silent"
116
+
117
+ [[case]]
118
+ prompt = "every time I push the build fails, can you suggest a fix?"
119
+ expect = "silent"
@@ -0,0 +1,102 @@
1
+ ---
2
+ name: hookmux
3
+ description: Builds hookmux plugins, which make Claude Code, Codex or Gemini CLI act on their own when a prompt or tool call matches. Use when the user asks to make, create, add or set up a hook; states a standing rule ("whenever I … remind/warn/block/suggest …", "every time I …"); or writes it in Vietnamese ("tạo hook", "mỗi khi tôi …", "bất cứ khi nào …"). Code hooks (React hooks, git hooks, webhooks) are a different subject.
4
+ ---
5
+
6
+ # hookmux plugin authoring
7
+
8
+ The user wants an automatic behaviour. You build it as a hookmux plugin, test it, install it in shadow mode, and hand the user the one command that makes it live. You stage; the user approves.
9
+
10
+ The full documentation is one text file at https://docs.khangle.dev/hookmux/llms-full.txt.
11
+
12
+ `hookmux schema --json` is the live reference for what the installed engine accepts. When it disagrees with this skill or its references, follow the engine. Each command's `--help` gives its exact arguments.
13
+
14
+ References, loaded when a step names them:
15
+
16
+ - `references/plugin-format.md`: manifest keys, `when` logic, phases, overrides, templates, tests.
17
+ - `references/check-kinds.md`: every check kind with its tier, whether it is model-backed, and its options.
18
+ - `references/effects.md`: effects and what each client supports on each event.
19
+ - `references/hosts.md`: event names per client.
20
+ - `references/examples/moodboard/`: a complete rules-only plugin with its `tests.toml`.
21
+
22
+ ## Workflow
23
+
24
+ ### 1. Restate the request as a plugin
25
+
26
+ Write down four values:
27
+
28
+ - Event: `prompt.submit`, `session.start`, `tool.before` or `tool.after`.
29
+ - Trigger: what makes it fire, and the near misses that must stay silent.
30
+ - Effect: `inject` (context for the agent), `block`, or `notify` (a message for the user).
31
+ - Phase: `guard` for a block, `route` for a suggestion, `enrich` for context added every time.
32
+
33
+ Ask the user only about a choice that changes the result, such as suggest or block. Check `references/effects.md` that the chosen client supports the effect on that event. Done when all four have a value.
34
+
35
+ ### 2. Look for an existing plugin
36
+
37
+ Run `hookmux list --json`. When an installed plugin already covers the request, change it with an `[override.<id>]` table in `~/.hookmux/config.toml` (`references/plugin-format.md`, Overrides) instead of adding a near-duplicate. Done when you know whether you are writing a new plugin or an override.
38
+
39
+ ### 3. Scaffold
40
+
41
+ Run `hookmux new <id>` with a lowercase, dash-separated id. It writes `plugin.toml` and `tests.toml`. `--template tool-guard` starts from a shell-command blocker, `--template session-note` from a script that adds a note at session start (tool and session events have no user origin, so tool-guard is a guard-phase plugin and session-note sets `origins = ["unknown"]`), and `--repo owner/name` adds a README and a CI workflow so the folder can be pushed and installed.
42
+
43
+ ### 4. Write the checks, cheapest first
44
+
45
+ Use `references/check-kinds.md` for kinds and options:
46
+
47
+ 1. Rules first: `regex`, `keywords` and `regex_groups` for prompt text, and `tool`, `cwd_glob`, `path_exists`, `host` or `origin` for context. Add an exempt check for each near miss and write `when` as `trigger and not exempt`.
48
+ 2. A model-backed kind only for a trigger that rules cannot express. Always pair it with `when_degraded`: a rules-only expression, or `"false"` to stay quiet when the model is unavailable.
49
+ 3. A script kind (tier 1) last, only when no built-in kind fits.
50
+
51
+ A `block` needs a rule check that is true, because model-backed checks cannot justify a block alone. Use TOML literal strings (`'...'`) for regular expressions. Put `\b` only next to ASCII letters; for accented words, use `keywords` or plain substrings. Flags default to case-insensitive.
52
+
53
+ Done when `hookmux validate <dir>` reports no problems.
54
+
55
+ ### 5. Write the tests
56
+
57
+ In `tests.toml`, add `[[case]]` entries with a `prompt` and `expect = "fire"` or `expect = "silent"`. Cover:
58
+
59
+ - each way the user phrased the request;
60
+ - the near misses from step 1, as silent cases, at least as many as the fire cases;
61
+ - every language the user writes prompts in, judged from this conversation.
62
+
63
+ ### 6. Verify
64
+
65
+ Run `hookmux validate <dir>`, then `hookmux test`, then `hookmux explain "<prompt>"` for one firing and one silent prompt. Script checks in a folder nobody promoted show as skipped; for a script you wrote yourself, add `--run-scripts` to `hookmux test <dir>`. Fix the checks until every case passes and `explain` shows the outcome you expect. Done when all three agree.
66
+
67
+ ### 7. Install in shadow mode
68
+
69
+ Run `hookmux add <dir> --shadow`. A shadow plugin is evaluated and logged, and adds nothing to the agent's context.
70
+
71
+ ### 8. Hand over
72
+
73
+ Tell the user what the plugin does (event, trigger, effect, and whether it can block) and the test results. Then run this as a Bash call by itself, with nothing else on the line:
74
+
75
+ ```sh
76
+ hookmux promote <id>
77
+ ```
78
+
79
+ What happens next depends on the client:
80
+
81
+ - In Claude Code and Qwen Code, when an installed plugin listens to `tool.before`, the client shows the user that call and waits. Without such a plugin, promote prints a card and a code as below. If they approve, the plugin goes live; if they decline, it stays off. Say what you are about to ask before you run it.
82
+ - In any other client, promote prints a card and a four-character code and exits 3. Show the user the card word for word and ask whether to turn the plugin on. Do not answer for them. If they agree, they reply `approve <code>` in their own message; hookmux reads that reply itself and tells you the exact command to run, `hookmux promote <id> --confirm <code>`. Run only that. If the plugin changes in between, run `hookmux promote <id>` again for a new card.
83
+
84
+ Running promote through a pseudo-terminal, adding `--yes`, writing a `--grant` yourself, running `--confirm` before the user has replied, feeding the hub a payload of your own, starting another agent client with the code as its prompt, wrapping the command so the hub does not see it, editing `~/.hookmux/trust.json`, the registry or the card files, and turning on `auto_trust_declarative` are all ways around the user's approval, so none of them is yours to do. A relayed approval never grants `--standing`.
85
+
86
+ Any later edit to the plugin folder un-trusts it until the user promotes it again. Say so when you change a live plugin. If the user granted a standing approval (`hookmux promote <id> --standing`), reinstall the changed plugin with `hookmux add <dir> --force` and it goes live while its capabilities stay within that approval; a new capability still needs the user's promote.
87
+
88
+ ## Installing a plugin for the user
89
+
90
+ When the user asks you to install a plugin someone else published ("install the X plugin with hookmux"), run the install line you were given, for example:
91
+
92
+ ```sh
93
+ npx -y hookmux install owner/name
94
+ ```
95
+
96
+ It sets hookmux up if needed, adds the plugin off, prints the plugin's card and a four-character code, and exits 3. Then:
97
+
98
+ 1. Show the user the card word for word. Do not shorten or reword it: the risk words and the "Can:" lines are what they decide on.
99
+ 2. Ask whether to turn the plugin on, and wait for their reply. Do not answer for them.
100
+ 3. When the user has replied with `approve <code>`, hookmux reads the reply itself and tells you the exact command to run, `hookmux promote <id> --confirm <code>`. Run that line and nothing else. If hookmux has not seen a reply, it says so; ask again instead of retrying.
101
+
102
+ This is the same on every client, Claude Code and Qwen Code included: their permission prompt covers only a bare `hookmux promote <id>` call. The same limits as in step 8 apply: no `--yes`, no `--standing`, no editing hookmux's files.