skill-autoroute 0.10.0 → 0.11.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.
package/README.md CHANGED
@@ -4,11 +4,11 @@
4
4
 
5
5
  **Your agent has dozens of skills. This tells it which one fits the prompt you just typed.**
6
6
 
7
- For Claude Code and Codex · No API key · Zero tokens when nothing matches
7
+ For Claude Code, Codex and Hermes · No API key · Zero tokens when nothing matches
8
8
 
9
9
  [![npm](https://img.shields.io/npm/v/skill-autoroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/skill-autoroute)
10
10
  ![node](https://img.shields.io/badge/node-%E2%89%A520.12-339933?logo=node.js&logoColor=white)
11
- ![tools](https://img.shields.io/badge/works%20with-Claude%20Code%20%7C%20Codex-8A63D2)
11
+ ![tools](https://img.shields.io/badge/works%20with-Claude%20Code%20%7C%20Codex%20%7C%20Hermes-8A63D2)
12
12
  ![license](https://img.shields.io/badge/license-MIT-blue)
13
13
 
14
14
  </div>
@@ -89,7 +89,7 @@ npx skill-autoroute install
89
89
 
90
90
  The installer walks you through it:
91
91
 
92
- 1. Pick your tools: Claude Code, Codex, or both.
92
+ 1. Pick your tools: Claude Code, Codex, Hermes, or any mix.
93
93
  2. Pick an AI helper: `claude`, `codex`, or `none` (keyword triggers, no AI calls).
94
94
  3. Review the skill list. Flagged skills start **unchecked**, with the reason beside the name.
95
95
  4. Try test prompts and see which hints they produce.
@@ -99,6 +99,9 @@ Each AI step shows a token estimate and asks before it runs.
99
99
 
100
100
  **Codex users:** after install, open Codex, run `/hooks`, and trust the skill-autoroute hook once.
101
101
 
102
+ **Hermes users:** the next time Hermes starts, it asks once to allow the new hook. Say yes. `hermes hooks list` shows
103
+ whether it is allowed. Hermes is a routed tool only: pick `claude`, `codex` or `none` as the AI helper.
104
+
102
105
  ### Prefer to let your agent do it?
103
106
 
104
107
  Paste this into Claude Code or Codex:
@@ -108,7 +111,7 @@ Paste this into Claude Code or Codex:
108
111
 
109
112
  ```text
110
113
  Set up skill-autoroute for me. Follow these steps exactly.
111
- 1. Ask me which tools to route (claude, codex, or both) and which AI helper to use (claude, codex, or none).
114
+ 1. Ask me which tools to route (claude, codex, hermes, or a mix) and which AI helper to use (claude, codex, or none).
112
115
  2. Run: npx skill-autoroute install --dry-run --tools <tools> --ai <ai>
113
116
  Show me the whole output, including the token estimates. Do not summarise it.
114
117
  3. Ask me whether to go ahead. Wait for a clear yes. If I say no, stop.
@@ -157,7 +160,7 @@ The optional AI scan can make a result stricter. It can never clear a high findi
157
160
 
158
161
  > [!WARNING]
159
162
  > "No issues found" means these rules found nothing. It is **not** a safety guarantee. Read skills you do not trust.
160
- > Unchecking a skill only removes its hints. Claude Code or Codex still loads the skill.
163
+ > Unchecking a skill only removes its hints. The tool still loads the skill.
161
164
 
162
165
  <details>
163
166
  <summary>More about scan limits</summary>
@@ -217,21 +220,37 @@ codex-cli 0.164.0. Your numbers will differ.
217
220
  ## Hint quality
218
221
 
219
222
  A wrong hint costs tokens and teaches the agent to ignore hints, so the trigger rules aim for precise hints, not many
220
- hints. Measured on 2026-10-28 on 1,616 real prompts from one developer's Claude Code history, with 148 installed skills.
221
- Sonnet graded 90 sampled prompts blind (was each hinted skill useful for that prompt?). A fixed check has 13 prompts with
222
- a known answer, 5 of which must get no hint.
223
+ hints. This table shows how often a hint was useful. It was measured on 1,616 real prompts from one developer's Claude
224
+ Code history (148 skills); Sonnet graded 90 of them blind.
225
+
226
+ | Trigger rules | Hints that were useful | Hint tokens per prompt |
227
+ | ---------------------------------------------------- | ---------------------- | ---------------------- |
228
+ | 0.2.0 | 36% | 12.9 |
229
+ | Broad single-word rules | 21% | 24.1 |
230
+ | **0.3.0 and later: task word plus object word** | **59%** | **10.8** |
223
231
 
232
+ Broader rules doubled the hints, but most of the new ones were wrong. Since 0.10.0 the rule generator also asks for the
233
+ task word and the object word to sit close together. On 1,136 prompts from one real history, useful hints rose from
234
+ 46% to about 55%, and about 80% of the earlier useful hints were kept (a different sample, so compare rows within one
235
+ line only).
224
236
 
225
- | Trigger rules | Precision | Relative recall | Useful / wrong hints | Hint tokens per prompt | Fixed check |
226
- | ------------------------------------------ | --------- | --------------- | -------------------- | ---------------------- | ----------- |
227
- | 0.2.0 (haiku) | 35.5% | 50.0% | 22 / 40 | 12.9 | 10/13 |
228
- | Broad single-word rules (haiku) | 21.0% | 59.1% | 26 / 98 | 24.1 | 9/13 |
229
- | **0.3.0 and later: task word plus object word (sonnet)** | **59.1%** | **59.1%** | **26 / 18** | **10.8** | **12/13** |
237
+ <details>
238
+ <summary>Full numbers for the 2026-10-28 measurement</summary>
230
239
 
240
+ | Trigger rules | Precision | Relative recall | Useful / wrong hints | Hint tokens per prompt | Fixed check |
241
+ | -------------------------------------------- | --------- | --------------- | -------------------- | ---------------------- | ----------- |
242
+ | 0.2.0 (haiku) | 35.5% | 50.0% | 22 / 40 | 12.9 | 10/13 |
243
+ | Broad single-word rules (haiku) | 21.0% | 59.1% | 26 / 98 | 24.1 | 9/13 |
244
+ | 0.3.0 and later (sonnet) | 59.1% | 59.1% | 26 / 18 | 10.8 | 12/13 |
231
245
 
232
- Relative recall is the share of all useful hints that any version found. Broader rules doubled the hints but most of the
233
- new ones were wrong. Guessing the kind of work from the prompt (question, change, risky) to gate or add hints was also
234
- tested and made hints worse (F1 63.2 down to 55.7), so it is not used.
246
+ Relative recall is the share of all useful hints that any version found. The fixed check has 13 prompts with a known
247
+ answer, 5 of which must get no hint. Guessing the kind of work from the prompt (question, change, risky) to gate or add
248
+ hints was also tested and made hints worse (F1 63.2 down to 55.7), so it is not used.
249
+
250
+ </details>
251
+
252
+ **Speed:** the hook starts in about 50 ms and the matching itself takes under 10 ms on a 227-skill table. A prompt with
253
+ no matching skill adds no tokens.
235
254
 
236
255
  Examples with 0.3.0 and later (0.4.0 added [your own trigger words](#your-own-trigger-words); the rules are the same):
237
256
 
@@ -289,7 +308,19 @@ List the acceptable skills in `expect`; an empty list marks a prompt that should
289
308
 
290
309
  ### Results so far
291
310
 
292
- Measured on 2026-11-10 with the eval above. Same matcher, same prompts, only the named change differs.
311
+ Measured on 2026-11-10 on one setup (227 skills). Higher is better.
312
+
313
+ | Change | Test | Before | After |
314
+ | --------------------------------------------------- | ------------------------------------ | ------ | ----- |
315
+ | Rules with close-together words (what 0.10.0 does) | Hints that were useful, 1,136 real prompts | 46% | about 55% |
316
+ | Your own trigger words for missed phrases | Right skill listed first, 35 hand-written prompts | 69% | 93% |
317
+ | Score ranking (opt-in, `SKILL_AUTOROUTE_RANK=score`) | Right skill listed first, 35 hand-written prompts | 69% | 69% (no change) |
318
+
319
+ In short: fixing rules and adding your own words helps. Reordering the hints did not help on real skills. It helped
320
+ only on the synthetic corpus, which is why it is off by default.
321
+
322
+ <details>
323
+ <summary>All measurements</summary>
293
324
 
294
325
  | What changed | Cases | P@1 before | P@1 after | recall@3 before | recall@3 after | No-match false positives |
295
326
  |---|---|---|---|---|---|---|
@@ -298,28 +329,20 @@ Measured on 2026-11-10 with the eval above. Same matcher, same prompts, only the
298
329
  | Own words added, real skills (hand-labeled) | 35 | 69.0% | 93.1% | 63.2% | 76.4% | 0% (unchanged) |
299
330
  | Own words added, second set written beforehand | 20 | 46.2% | 92.3% | 38.5% | 69.2% | 0% (unchanged) |
300
331
 
301
- On 1,136 real prompts from one developer's history (321 hinted skill-and-prompt pairs, graded blind by Sonnet), hint
302
- precision was 46.4% with the original generated rules. Rewriting nine skills' rules so the task word and object word sit
303
- close together (what the generator now asks for) gave about 55%, and kept about 80% of the useful hints. Own words and
304
- score ranking changed almost nothing on that history. This is a different method from the table above, so compare the
305
- rows only with each other.
306
-
307
332
  Score ranking costs about 0.3 ms per prompt (6.7 ms to 7.0 ms on a 227-skill table). Own words cost nothing extra.
333
+ On 1,136 real prompts (321 hinted skill-and-prompt pairs, graded blind by Sonnet), hint precision was 46.4% with the
334
+ original generated rules and about 55% with nine skills' rules rewritten, keeping about 80% of the useful hints. Own
335
+ words and score ranking changed almost nothing on that history.
308
336
 
309
- Read it this way:
310
-
311
- - Ordering did not help on real skills. The gain came from prompts that matched no skill at all. Adding specific
312
- phrases (English and Indonesian) as own words fixed most of them.
313
- - The real-skill rows come from one person's setup (227 skills) and labels. Those prompt sets are not published.
314
- The second set was written before the own words, but the phrases were chosen knowing it, so part of that gain is
315
- fitting. Expect a smaller gain on your own skills, and measure it.
337
+ </details>
316
338
 
317
- What the numbers mean and do not mean:
339
+ What these numbers do not show:
318
340
 
341
+ - They come from one person's setup and labels, and the prompt sets are not published. The second set was written
342
+ before the own words, but the phrases were chosen knowing it, so part of that gain is fitting. Expect a smaller gain
343
+ on your own skills, and measure it.
319
344
  - The bundled corpus is synthetic. It shows direction, not how your skills will behave. Write 20 to 30 prompts of your
320
345
  own, with your own skill names, before you trust a change.
321
- - Score ranking (`SKILL_AUTOROUTE_RANK=score`) raised P@1 on the synthetic corpus and made no difference on a
322
- hand-labeled set of real skills. The bigger gain there came from adding own words for prompts that matched nothing.
323
346
  - Labels are judgment calls. With about 35 prompts one case is worth about 3 points, so small differences are noise.
324
347
 
325
348
  ---
@@ -360,7 +383,7 @@ npx skill-autoroute install --model triggers=haiku
360
383
  | `uninstall` | Remove the hook, the table and the hook copy |
361
384
 
362
385
 
363
- **Flags:** `--yes` (accept defaults) · `--dry-run` (estimates only, writes nothing) · `--project` · `--tools claude,codex`
386
+ **Flags:** `--yes` (accept defaults) · `--dry-run` (estimates only, writes nothing) · `--project` · `--tools claude,codex,hermes`
364
387
  · `--ai claude|codex|none` · `--model step=model` · `--log`
365
388
 
366
389
  When your skills change, the hint line tells you so. Run `regenerate`.
@@ -410,6 +433,25 @@ Enabled means eligible for routing on matching prompts, not that the agent has i
410
433
  - **Project level** goes into the repository, so teammates get it on clone. It adds a hook to `.claude/settings.json`.
411
434
  Paths are stored relative to the project, and entries that point outside the project are skipped.
412
435
  - **Codex** has a user-level hook only. That hook still reads the project table of the folder you run Codex in.
436
+ - **Hermes** also has a user-level hook only (`hooks.pre_llm_call` in `~/.hermes/config.yaml`, written with
437
+ `hermes config set`). It reads the project table of the folder Hermes runs in, and `--project` lists the skills in a
438
+ trusted project's `.hermes/skills` and `.agents/skills`.
439
+
440
+ <details>
441
+ <summary>How the Hermes adapter works</summary>
442
+
443
+ - **Skills:** it lists `$HERMES_HOME/skills` (default `~/.hermes/skills`) with its category folders, plus every folder in
444
+ `skills.external_dirs`. It leaves out what Hermes does not load in a normal session: skills in `skills.disabled`,
445
+ skills for another platform (`platforms:`) and skills limited to special environments such as Kanban workers
446
+ (`environments:`). It reads the settings with `hermes config get`, so it needs no YAML parser.
447
+ - **Hook:** `pre_llm_call` fires once per user turn, before the model runs. The hook reads the prompt from
448
+ `extra.user_message` (the text parts on an image or file turn) and replies `{"context": "..."}`, which Hermes adds to
449
+ the user message. No match prints nothing.
450
+ - **Subagents:** a second entry on `subagent_start` records each `delegate_task` child's session id, and the child's
451
+ turns get no hints. The parent already chose the work.
452
+ - **Config:** the first change backs up `config.yaml` to `config.yaml.bak-skill-autoroute`. Other hooks stay as they are.
453
+
454
+ </details>
413
455
 
414
456
  <details class="orca-details">
415
457
  <summary>How the hook stays safe and quiet</summary>
@@ -439,13 +481,14 @@ It removes only its own hook entries. Backups of your config files (`*.bak-skill
439
481
  ## Requirements
440
482
 
441
483
  - Node **20.12+**
442
- - Claude Code and/or Codex CLI. For AI steps, log in to `claude` or `codex`, or use `--ai none`.
484
+ - Claude Code, Codex and/or Hermes. For AI steps, log in to `claude` or `codex`, or use `--ai none`.
443
485
  - Linux or macOS. Windows is untested.
444
486
 
445
487
  ## Supported tools
446
488
 
447
- Version 1 supports **Claude Code** and **Codex**. These two have both a prompt hook and a headless mode that work with
448
- your normal login. Notes on Kiro, Cline, opencode, Amp, Cursor, Copilot CLI, Windsurf and Antigravity are in
489
+ Version 1 supports **Claude Code**, **Codex** and **Hermes**. Claude Code and Codex have both a prompt hook and a
490
+ headless mode that work with your normal login. Hermes has the prompt hook (`pre_llm_call`) but is not used as the AI
491
+ helper: its one-shot mode has no schema-checked output and no read-only switch for reading untrusted skill text. Notes on Kiro, Cline, opencode, Amp, Cursor, Copilot CLI, Windsurf and Antigravity are in
449
492
  [the design document](docs/specs/2026-10-28-skill-autoroute-design.md#12). Each tool is one adapter file in
450
493
  `src/tools/`.
451
494
 
@@ -455,7 +498,8 @@ your normal login. Notes on Kiro, Cline, opencode, Amp, Cursor, Copilot CLI, Win
455
498
  npm test
456
499
  ```
457
500
 
458
- The tests use fake `claude` and `codex` programs and a fake `HOME`. They make no real AI calls.
501
+ The tests use fake `claude`, `codex` and `hermes` programs and a fake `HOME`. They make no real AI calls and never touch
502
+ your real Hermes config.
459
503
 
460
504
  ## License
461
505
 
package/bin/cli.js CHANGED
@@ -7,7 +7,7 @@ import { STEP_DEFAULTS } from '../src/models.js';
7
7
 
8
8
  const USAGE = `usage: skill-autoroute <command> [flags]
9
9
  commands: install | regenerate | scan | list [<skill>] | set <skill> on|off | words [<skill> [add|remove <word>...]] | status | tokens | bench | uninstall
10
- flags: --yes --dry-run --project --tools claude,codex --ai claude|codex|none --model step=model (repeatable) --log`;
10
+ flags: --yes --dry-run --project --tools claude,codex,hermes --ai claude|codex|none --model step=model (repeatable) --log`;
11
11
 
12
12
  const COMMANDS = {
13
13
  install: flow.install, regenerate: flow.regenerate, scan: flow.scan, set: flow.setSkill, words: flow.setWords,
@@ -23,7 +23,7 @@ function options() {
23
23
  },
24
24
  });
25
25
  const tools = v.tools?.split(',').map((t) => t.trim()).filter(Boolean);
26
- for (const t of tools ?? []) if (!flow.ADAPTERS[t]) throw new Error(`unknown tool "${t}" (claude, codex)`);
26
+ for (const t of tools ?? []) if (!flow.ADAPTERS[t]) throw new Error(`unknown tool "${t}" (claude, codex, hermes)`);
27
27
  if (v.ai && !['claude', 'codex', 'none'].includes(v.ai)) throw new Error(`unknown --ai "${v.ai}" (claude, codex, none)`);
28
28
  const models = {};
29
29
  for (const m of v.model ?? []) {
package/hook/route.js CHANGED
@@ -1,6 +1,6 @@
1
- // Per-prompt hook for Claude Code and Codex. Node built-ins only; any error means no output, exit 0.
2
- // argv[2] names the tool (claude or codex): only that tool's skills are hinted; no argument hints all.
3
- import { readFileSync, statSync, readdirSync, realpathSync, appendFileSync, mkdirSync, existsSync, unlinkSync } from 'node:fs';
1
+ // Per-prompt hook for Claude Code, Codex and Hermes. Node built-ins only; any error means no output, exit 0.
2
+ // argv[2] names the tool (claude, codex or hermes): only that tool's skills are hinted; no argument hints all.
3
+ import { readFileSync, statSync, readdirSync, realpathSync, appendFileSync, mkdirSync, existsSync, unlinkSync, writeFileSync } from 'node:fs';
4
4
  import { join, dirname, resolve, sep } from 'node:path';
5
5
  import { homedir } from 'node:os';
6
6
  import { pathToFileURL } from 'node:url';
@@ -151,7 +151,8 @@ const ownFits = (s, text) => { const src = wordsPattern(s.words); return Boolean
151
151
  export function staleCount(table, fs = FS) {
152
152
  const gen = Date.parse(table.generatedAt);
153
153
  const entries = table.skills.filter((s) => s && typeof s.path === 'string');
154
- const known = new Set(entries.map((s) => dirname(s.path)));
154
+ // `ignored`: skill folders the tool does not load (turned off, other platform). They are not new skills.
155
+ const known = new Set([...entries.map((s) => dirname(s.path)), ...(Array.isArray(table.ignored) ? table.ignored : [])]);
155
156
  let n = 0;
156
157
  for (const { path: p, project } of entries) {
157
158
  const m = fs.mtime(p);
@@ -227,6 +228,7 @@ function clean(t) {
227
228
  ...t,
228
229
  skills: t.skills.filter((s) => s && typeof s === 'object' && !Array.isArray(s)),
229
230
  roots: Array.isArray(t.roots) ? t.roots.filter((r) => typeof r === 'string') : [],
231
+ ignored: Array.isArray(t.ignored) ? t.ignored.filter((r) => typeof r === 'string') : [],
230
232
  };
231
233
  }
232
234
 
@@ -240,6 +242,7 @@ export function resolveProject(table, base) {
240
242
  return {
241
243
  ...t,
242
244
  roots: t.roots.map(abs).filter(under),
245
+ ignored: t.ignored.map(abs).filter(under),
243
246
  skills: t.skills.filter((s) => typeof s.path === 'string' && under(abs(s.path))).map((s) => ({ ...s, path: abs(s.path), project: true })),
244
247
  };
245
248
  }
@@ -254,6 +257,7 @@ export function merge(user, project) {
254
257
  ...u,
255
258
  generatedAt: gens[0] ?? '',
256
259
  roots: [...new Set([...u.roots, ...p.roots])],
260
+ ignored: [...new Set([...u.ignored, ...p.ignored])],
257
261
  skills: [...u.skills.filter((s) => !names.has(s.name)), ...p.skills],
258
262
  ...(u.log === true || p.log === true ? { log: true } : {}),
259
263
  };
@@ -351,6 +355,45 @@ function suggestJson(udir, args, i) {
351
355
  if (selected.length) remember(file, detail.map((d) => d.name));
352
356
  }
353
357
 
358
+ // The text of a Hermes user message: a string, or (an image or file turn) a list of content parts.
359
+ export function messageText(m) {
360
+ if (typeof m === 'string') return m;
361
+ if (!Array.isArray(m)) return null;
362
+ const parts = m.map((p) => (typeof p === 'string' ? p : p && p.type === 'text' && typeof p.text === 'string' ? p.text : null)).filter((t) => t !== null);
363
+ return parts.length ? parts.join('\n') : null;
364
+ }
365
+
366
+ // Hermes delegated children: `subagent_start` names the child session before it runs, and its turns get no hints
367
+ // (the parent already chose the work). One empty marker file per child, pruned with the session files.
368
+ const childFile = (udir, sid) => sessionFile(udir, 'hermes-child', sid);
369
+ function markChild(udir, sid) {
370
+ const file = childFile(udir, sid);
371
+ if (!file) return;
372
+ try { mkdirSync(dirname(file), { recursive: true }); writeFileSync(file, ''); } catch { /* a read-only folder only loses the mark */ }
373
+ }
374
+
375
+ // What the tool sent, as {prompt, sid, base}; null when there is nothing to route.
376
+ // Claude Code and Codex send {prompt, session_id}. Hermes sends {hook_event_name, session_id, cwd, extra: {user_message}}.
377
+ export function readInput(input, tool, udir) {
378
+ if (!input || typeof input !== 'object') return null;
379
+ if (tool === 'hermes') {
380
+ if (input.hook_event_name === 'subagent_start') { markChild(udir, input.extra?.child_session_id); return null; }
381
+ if (input.hook_event_name !== undefined && input.hook_event_name !== 'pre_llm_call') return null;
382
+ const sid = input.session_id;
383
+ if (childFile(udir, sid) && existsSync(childFile(udir, sid))) return null;
384
+ const prompt = messageText(input.extra?.user_message);
385
+ if (prompt === null) return null;
386
+ return { prompt, sid, base: typeof input.cwd === 'string' && input.cwd ? input.cwd : process.cwd() };
387
+ }
388
+ if (typeof input.prompt !== 'string') return null;
389
+ return { prompt: input.prompt, sid: input.session_id, base: process.env.CLAUDE_PROJECT_DIR || process.cwd() };
390
+ }
391
+
392
+ // Hermes reads {"context"}; Claude Code and Codex read hookSpecificOutput.additionalContext.
393
+ export const hookOutput = (tool, ctx) => (tool === 'hermes'
394
+ ? { context: ctx }
395
+ : { hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: ctx } });
396
+
354
397
  function main(self) {
355
398
  if (process.env.SKILL_AUTOROUTE_DISABLE === '1') return;
356
399
  const udir = join(homedir(), '.config', 'skill-autoroute');
@@ -361,12 +404,12 @@ function main(self) {
361
404
  // Only a Claude user hook counts: a Codex-only user install must not silence the Claude project hook.
362
405
  if (self.endsWith(`${sep}.skill-autoroute${sep}route.mjs`) && userClaudeHook(udir)) return;
363
406
  try {
364
- const { prompt, session_id: sid } = JSON.parse(readFileSync(0, 'utf8'));
365
- if (typeof prompt !== 'string') return;
366
- const base = process.env.CLAUDE_PROJECT_DIR || process.cwd();
407
+ const tool = args[0];
408
+ const input = readInput(JSON.parse(readFileSync(0, 'utf8')), tool, udir);
409
+ if (!input) return;
410
+ const { prompt, sid, base } = input;
367
411
  const table = loadTable(udir, base);
368
412
  if (!table) return;
369
- const tool = args[0];
370
413
  const file = sessionFile(udir, tool, sid);
371
414
  const known = file && remembered(file);
372
415
  const hit = pick(prompt, table, { tool, base, skip: known ?? undefined });
@@ -377,7 +420,7 @@ function main(self) {
377
420
  if (!hit && !tell) return;
378
421
  remember(file, hit ? hit.names : []);
379
422
  const ctx = [hit?.out, tell].filter(Boolean).join('\n');
380
- process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: ctx } }) + '\n');
423
+ process.stdout.write(JSON.stringify(hookOutput(tool, ctx)) + '\n');
381
424
  if (process.env.SKILL_AUTOROUTE_LOG === '1' || table.log === true) {
382
425
  try {
383
426
  mkdirSync(udir, { recursive: true });
package/package.json CHANGED
@@ -1,10 +1,11 @@
1
1
  {
2
2
  "name": "skill-autoroute",
3
- "version": "0.10.0",
4
- "description": "Per-prompt skill router hook for Claude Code and Codex",
3
+ "version": "0.11.0",
4
+ "description": "Per-prompt skill router hook for Claude Code, Codex and Hermes",
5
5
  "keywords": [
6
6
  "claude-code",
7
7
  "codex",
8
+ "hermes",
8
9
  "skills",
9
10
  "agent",
10
11
  "hook",
package/skill/SKILL.md CHANGED
@@ -19,7 +19,7 @@ relaying the output. You do not do any of the work yourself.
19
19
 
20
20
  ## Steps
21
21
 
22
- 1. Ask which tools to route (`claude`, `codex`, or both) and which AI helper makes the scan and the triggers (`claude`,
22
+ 1. Ask which tools to route (`claude`, `codex`, `hermes`, or a mix) and which AI helper makes the scan and the triggers (`claude`,
23
23
  `codex`, or `none` for keyword triggers with no AI calls). If the user does not know, run
24
24
  `npx skill-autoroute status` and show which CLIs it found.
25
25
  2. Run the dry run, with the answers from step 1:
@@ -48,6 +48,8 @@ relaying the output. You do not do any of the work yourself.
48
48
  A skill turned on this way has no trigger rules until `npx skill-autoroute regenerate` runs.
49
49
  7. If Codex was chosen, tell the user to run `/hooks` once inside Codex and trust the new hook. Until then Codex does
50
50
  not run it.
51
+ 8. If Hermes was chosen, tell the user that Hermes asks once to allow the new hook the next time it starts, and that
52
+ `hermes hooks list` shows whether it is allowed. Hermes cannot be the AI helper; use `claude`, `codex` or `none`.
51
53
 
52
54
  ## Later
53
55
 
package/src/discover.js CHANGED
@@ -63,10 +63,11 @@ function walk(root, realDir, rel, seen, found, outside, skipped) {
63
63
  }
64
64
  }
65
65
 
66
- export function discover(dirs) {
66
+ // `ignored` (optional) collects the real folders a `skip` callback left out.
67
+ export function discover(dirs, ignored = []) {
67
68
  const skills = [];
68
69
  const done = new Map(); // real dir -> skill, so a folder shared by two tools lists both
69
- for (const { dir, tool, source, projects, only } of dirs) {
70
+ for (const { dir, tool, source, projects, only, skip } of dirs) {
70
71
  let names;
71
72
  try { names = readdirSync(dir).sort(); } catch { continue; }
72
73
  if (Array.isArray(only)) names = names.filter((n) => only.includes(n));
@@ -90,6 +91,8 @@ export function discover(dirs) {
90
91
  if (!inside(real, sr) || !statSync(sr).isFile()) continue;
91
92
  text = readFileSync(sr, 'utf8');
92
93
  } catch { continue; }
94
+ // `skip(name, text)` is true for a skill the tool does not load; another tool listing the same folder still lists it.
95
+ if (typeof skip === 'function' && skip(parseFrontmatter(text).name || folder, text)) { if (!ignored.includes(real)) ignored.push(real); continue; }
93
96
  done.set(real, null);
94
97
  const found = [];
95
98
  const outside = [];
package/src/flow.js CHANGED
@@ -5,6 +5,7 @@ import { createHash } from 'node:crypto';
5
5
  import { relative, sep } from 'node:path';
6
6
  import * as claude from './tools/claude.js';
7
7
  import * as codex from './tools/codex.js';
8
+ import * as hermes from './tools/hermes.js';
8
9
  import { discover } from './discover.js';
9
10
  import { scanStatic, label } from './scan/static.js';
10
11
  import { aiScan, mergeScan } from './scan/ai.js';
@@ -17,7 +18,9 @@ import { routesPath, reportPath, hookCopyPath, logPath } from './paths.js';
17
18
  import { installHookCopy, hookCommand, checkConfig } from './tools/hookconfig.js';
18
19
  import { route, staleCount, resolveProject, wordsPattern } from '../hook/route.js';
19
20
 
20
- export const ADAPTERS = { claude, codex };
21
+ export const ADAPTERS = { claude, codex, hermes };
22
+ // Tools whose CLI can run the AI helper steps (Hermes routes prompts but has no schema-checked headless mode).
23
+ const helpers = () => Object.keys(ADAPTERS).filter((n) => typeof ADAPTERS[n].headless === 'function');
21
24
  export class Cancel extends Error {}
22
25
 
23
26
  const BATCH = 20;
@@ -49,7 +52,11 @@ export function findTools() {
49
52
 
50
53
  export function findSkills(tools, scope) {
51
54
  const dirs = tools.flatMap((t) => ADAPTERS[t].skillDirs(scope));
52
- return { skills: discover(dirs), roots: dirs.map((d) => d.dir).filter((d) => existsSync(d)) };
55
+ const ignored = [];
56
+ const skills = discover(dirs, ignored);
57
+ // A folder skipped by one tool but listed by another is a known skill, not an ignored one.
58
+ const listed = new Set(skills.map((s) => s.dir));
59
+ return { skills, roots: dirs.map((d) => d.dir).filter((d) => existsSync(d)), ignored: ignored.filter((d) => !listed.has(d)) };
53
60
  }
54
61
 
55
62
  // Characters sent: exact trigger prompts; scan and dedupe approximated from file sizes, capped as the modules cap them.
@@ -200,15 +207,19 @@ const entry = (r, gen, scope) => {
200
207
  // Every entry stores a hash of the rules as generated. A rule list that no longer matches its hash was edited by the user.
201
208
  export const rulesHash = (patterns) => createHash('sha256').update(JSON.stringify(patterns ?? [])).digest('hex').slice(0, 16);
202
209
  const edited = (w) => Boolean(w?.rulesHash) && rulesHash(w.patterns) !== w.rulesHash;
203
- const tableOf = (ctx, skills, roots, log) => ({
210
+ const tableOf = (ctx, skills, roots, log, ignored = []) => ({
204
211
  version: 1, generatedAt: new Date().toISOString(),
205
212
  generator: { ai: ctx.ai ? ctx.aiName : 'none', model: ctx.ai ? pickModel(ctx.aiName, 'triggers', ctx.overrides).model ?? null : null, overheadPerCall: ctx.overhead, cacheReadPerCall: ctx.cacheOverhead, rules: RULES_VERSION },
206
- roots, ...(log ? { log: true } : {}), skills: skills.map((s) => (s.rulesHash ? s : { ...s, rulesHash: rulesHash(s.patterns) })),
213
+ roots, ...(ignored.length ? { ignored } : {}), ...(log ? { log: true } : {}), skills: skills.map((s) => (s.rulesHash ? s : { ...s, rulesHash: rulesHash(s.patterns) })),
207
214
  });
208
215
 
209
216
  // Every tool config must parse before anything is written (throws naming the bad file).
210
217
  export function preflight(scope, tools) {
211
- for (const t of tools) { const p = ADAPTERS[t].hookConfig(scope); if (p) checkConfig(p); }
218
+ for (const t of tools) {
219
+ const a = ADAPTERS[t];
220
+ if (a.checkConfig) a.checkConfig(scope);
221
+ else { const p = a.hookConfig(scope); if (p) checkConfig(p); }
222
+ }
212
223
  }
213
224
 
214
225
  export function write(scope, table, tools, ctx) {
@@ -230,13 +241,18 @@ export function write(scope, table, tools, ctx) {
230
241
 
231
242
  // Runs the exact hook command written to the tool config and checks the output shape (empty, or one JSON line with additionalContext).
232
243
  export function selfTest(scope, tool) {
244
+ const a = ADAPTERS[tool];
245
+ const text = 'skill-autoroute self-test';
233
246
  const r = spawnSync(hookCommand(scope, tool), {
234
- shell: true, input: JSON.stringify({ prompt: 'skill-autoroute self-test' }), encoding: 'utf8', timeout: 10000,
247
+ shell: true, input: JSON.stringify(a?.testInput ? a.testInput(text, process.cwd()) : { prompt: text }), encoding: 'utf8', timeout: 10000,
235
248
  env: { ...process.env, CLAUDE_PROJECT_DIR: process.cwd() },
236
249
  });
237
250
  if (r.status !== 0) return false;
238
251
  if (!r.stdout.trim()) return true;
239
- try { return typeof JSON.parse(r.stdout).hookSpecificOutput.additionalContext === 'string'; } catch { return false; }
252
+ try {
253
+ const o = JSON.parse(r.stdout);
254
+ return a?.outputOk ? a.outputOk(o) : typeof o.hookSpecificOutput.additionalContext === 'string';
255
+ } catch { return false; }
240
256
  }
241
257
 
242
258
  // Steps 1 to 5 shared by install and scan: tools, AI helper with probe, skills, static scan.
@@ -244,8 +260,8 @@ async function prelude(o, ui) {
244
260
  const found = findTools();
245
261
  const avail = found.filter((t) => t.cli || t.configDir).map((t) => t.name);
246
262
  const tools = o.tools ?? (await ui.multiselect('Tools to route', found.map((t) => ({ value: t.name, label: t.name, hint: t.cli ? 'CLI found' : t.configDir ? 'config only' : 'not found' })), avail));
247
- if (!tools.length) throw new Error('no tool chosen; pass --tools claude,codex');
248
- const clis = found.filter((t) => t.cli).map((t) => t.name);
263
+ if (!tools.length) throw new Error('no tool chosen; pass --tools claude,codex,hermes');
264
+ const clis = found.filter((t) => t.cli && helpers().includes(t.name)).map((t) => t.name);
249
265
  const aiName = o.ai ?? (await ui.select('AI helper for scan, duplicates and triggers', [...clis.map((n) => ({ value: n, label: n })), { value: 'none', label: 'none (keywords only)' }], clis.find((n) => tools.includes(n)) ?? clis[0] ?? 'none'));
250
266
  const ctx = context(aiName, o);
251
267
  if (ctx.ai) {
@@ -261,11 +277,11 @@ async function prelude(o, ui) {
261
277
  }
262
278
  }
263
279
  const scope = scopeOf(o);
264
- const { skills, roots } = findSkills(tools, scope);
280
+ const { skills, roots, ignored } = findSkills(tools, scope);
265
281
  const counts = {};
266
282
  for (const s of skills) { const k = `${s.tool} ${show(s.source)}`; counts[k] = (counts[k] ?? 0) + 1; }
267
283
  ui.log(`skills found: ${skills.length}${Object.keys(counts).length ? ` (${Object.entries(counts).map(([k, v]) => `${k}: ${v}`).join(', ')})` : ''}`);
268
- return { scope, tools, ctx, skills, roots };
284
+ return { scope, tools, ctx, skills, roots, ignored };
269
285
  }
270
286
 
271
287
  function dryRun(ctx, skills, ui) {
@@ -291,13 +307,13 @@ function summary(ctx, gen, notes, ui) {
291
307
  }
292
308
 
293
309
  export async function install(o, ui) {
294
- const { scope, tools, ctx, skills, roots } = await prelude(o, ui);
310
+ const { scope, tools, ctx, skills, roots, ignored } = await prelude(o, ui);
295
311
  if (o.dryRun) return dryRun(ctx, skills, ui);
296
312
  preflight(scope, tools); // fail before spending AI calls
297
313
  const scans = await runScans(skills, ctx, ui);
298
314
  const rows = await pickRows(buildRows(skills, scans, await runDedupe(skills, ctx, ui)), ui);
299
315
  const gen = await generate(rows.filter((r) => r.enabled).map((r) => r.skill), ctx, ui);
300
- const table = tableOf(ctx, rows.map((r) => entry(r, gen, scope)), roots.map(keyOf(scope)), o.log);
316
+ const table = tableOf(ctx, rows.map((r) => entry(r, gen, scope)), roots.map(keyOf(scope)), o.log, ignored.map(keyOf(scope)));
301
317
  keepWords(table, readTable(routesPath(scope)));
302
318
  keepEdited(table, readTable(routesPath(scope)), ui);
303
319
  while (!ui.yes) {
@@ -329,7 +345,7 @@ export async function regenerate(o, ui) {
329
345
  const key = keyOf(scope);
330
346
  const prev = new Map(old.skills.map((s) => [s.path, s]));
331
347
  const was = (s) => prev.get(key(s.skillPath));
332
- const { skills, roots } = findSkills(tools, scope);
348
+ const { skills, roots, ignored } = findSkills(tools, scope);
333
349
  ctx.cacheOverhead = Number(old.generator?.cacheReadPerCall) || 0;
334
350
  const fresh = skills.filter((s) => was(s)?.hash !== s.hash);
335
351
  // unchanged and enabled but without rules (turned on with `set` after generate), or with rules from an older RULES_VERSION: they only need rules
@@ -355,7 +371,7 @@ export async function regenerate(o, ui) {
355
371
  }
356
372
  // Scope comes from this discovery, not the old entry: enabling a plugin in another project changes no skill file.
357
373
  const scoped = ({ projects, ...e }, s) => (s.projects ? { ...e, projects: s.projects } : e);
358
- const table = tableOf(ctx, skills.map((s) => scoped(byPath.get(s.skillPath) ?? was(s), s)), roots.map(key), old.log);
374
+ const table = tableOf(ctx, skills.map((s) => scoped(byPath.get(s.skillPath) ?? was(s), s)), roots.map(key), old.log, ignored.map(key));
359
375
  keepWords(table, old);
360
376
  keepEdited(table, old, ui);
361
377
  // unchanged rules still come from the old generator; after a full rebuild the new model wrote them all
@@ -553,7 +569,7 @@ const SAMPLES = [
553
569
 
554
570
  // Ruling R31: the CLI runs with the user's settings so the hook fires; DISABLE=1 gives the baseline.
555
571
  export async function bench(o, ui) {
556
- const aiName = o.ai ?? findTools().find((t) => t.cli)?.name;
572
+ const aiName = o.ai ?? findTools().find((t) => t.cli && helpers().includes(t.name))?.name;
557
573
  if (!aiName || aiName === 'none') throw new Error('bench needs an AI CLI: pass --ai claude or --ai codex');
558
574
  const ctx = context(aiName, o);
559
575
  const m = model(ctx, 'probe');
@@ -0,0 +1,163 @@
1
+ import { existsSync, readdirSync, statSync, copyFileSync } from 'node:fs';
2
+ import { spawnSync } from 'node:child_process';
3
+ import { homedir } from 'node:os';
4
+ import { join } from 'node:path';
5
+ import { onPath } from './run.js';
6
+
7
+ export const name = 'hermes';
8
+
9
+ // Hermes keeps every file under HERMES_HOME (a profile sets it); the default is ~/.hermes.
10
+ export const hermesHome = () => process.env.HERMES_HOME || join(homedir(), '.hermes');
11
+ const configFile = () => join(hermesHome(), 'config.yaml');
12
+
13
+ const MARK = 'skill-autoroute/route.mjs';
14
+ // pre_llm_call fires once per user turn and injects {"context"}; subagent_start lets the hook skip delegated children.
15
+ export const EVENTS = ['pre_llm_call', 'subagent_start'];
16
+ const TIMEOUT = 10;
17
+ const NO_PROJECT = { changed: false, note: 'hermes uses the user-level hook; it reads the project table' };
18
+ const isObj = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
19
+ const ours = (h) => isObj(h) && typeof h.command === 'string' && h.command.includes(MARK);
20
+
21
+ export const detect = () => ({ cli: onPath('hermes'), configDir: existsSync(hermesHome()) });
22
+
23
+ // Settings are read and written through the Hermes CLI: no YAML parser here, and Hermes keeps its own
24
+ // file checks. The CLI runs only when a Hermes folder exists, so a machine without Hermes never spawns it.
25
+ function cli(args) {
26
+ if (!existsSync(hermesHome()) || !onPath('hermes')) return null;
27
+ return spawnSync('hermes', args, { encoding: 'utf8', timeout: 60000 });
28
+ }
29
+
30
+ // The JSON value of `key`; undefined when the key is unset, Hermes is missing or the output is not JSON.
31
+ export function getKey(key) {
32
+ const r = cli(['config', 'get', '--json', key]);
33
+ if (!r || r.status !== 0) return undefined;
34
+ try { return JSON.parse(r.stdout); } catch { return undefined; }
35
+ }
36
+
37
+ function setKey(key, value) {
38
+ const r = cli(['config', 'set', key, JSON.stringify(value)]);
39
+ if (!r) throw new Error('the hermes CLI was not found on PATH; install or start Hermes first, nothing was changed');
40
+ if (r.status !== 0) throw new Error(`hermes config set ${key} failed: ${(r.stderr || r.stdout).trim().slice(0, 200)}`);
41
+ }
42
+
43
+ const names = (v) => (Array.isArray(v) ? v : typeof v === 'string' ? [v] : []).map((s) => String(s).trim()).filter(Boolean);
44
+
45
+ // `~` and ${VAR} / $VAR, as Hermes expands skills.external_dirs.
46
+ const expand = (p) => String(p)
47
+ .replace(/^~(?=$|[\\/])/, homedir())
48
+ .replace(/\$\{(\w+)\}|\$(\w+)/g, (m, a, b) => process.env[a ?? b] ?? m);
49
+
50
+ // Hermes nests skills in category folders (skills/<category>/<skill>/SKILL.md). discover() lists the skill
51
+ // folders inside one dir, so every folder without a SKILL.md is a container whose children are listed too.
52
+ // Skill folders are never walked: their subfolders are references and scripts.
53
+ function containers(root, depth = 0, out = []) {
54
+ out.push(root);
55
+ if (depth >= 3) return out;
56
+ let entries;
57
+ try { entries = readdirSync(root).sort(); } catch { return out; }
58
+ for (const n of entries) {
59
+ if (n.startsWith('.') || n === 'node_modules') continue;
60
+ const p = join(root, n);
61
+ try {
62
+ if (!statSync(p).isDirectory() || existsSync(join(p, 'SKILL.md'))) continue;
63
+ } catch { continue; }
64
+ containers(p, depth + 1, out);
65
+ }
66
+ return out;
67
+ }
68
+
69
+ const PLATFORM = { darwin: 'macos', win32: 'windows', linux: 'linux' }[process.platform] ?? process.platform;
70
+
71
+ // The values of a top-level frontmatter list (`key: [a, b]` or an indented `- a` block); null when the key is absent.
72
+ export function frontmatterList(text, key) {
73
+ const fm = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---/.exec(text)?.[1];
74
+ if (!fm) return null;
75
+ const m = new RegExp(`^${key}:[ \\t]*(.*)$`, 'm').exec(fm);
76
+ if (!m) return null;
77
+ if (m[1].trim()) return m[1].replace(/^\[|\]$/g, '').split(',').map((s) => s.trim().replace(/^(["'])(.*)\1$/, '$2')).filter(Boolean);
78
+ const after = fm.slice(m.index + m[0].length).split(/\r?\n/).slice(1);
79
+ const out = [];
80
+ for (const l of after) {
81
+ const item = /^\s+-\s*(.+)$/.exec(l);
82
+ if (!item) break;
83
+ out.push(item[1].trim().replace(/^(["'])(.*)\1$/, '$2'));
84
+ }
85
+ return out;
86
+ }
87
+
88
+ // True for a skill Hermes does not load in a normal session: turned off in skills.disabled, made for another
89
+ // platform (`platforms:`), or limited to special environments such as Kanban workers (`environments:`).
90
+ export const hiddenBy = (disabled) => (skillName, text) => {
91
+ if (disabled.includes(skillName)) return true;
92
+ const platforms = frontmatterList(text, 'platforms');
93
+ if (platforms && platforms.length && !platforms.includes(PLATFORM)) return true;
94
+ return Boolean(frontmatterList(text, 'environments')?.length);
95
+ };
96
+
97
+ // Each scope lists only its own dirs, without the skills Hermes would not load.
98
+ export function skillDirs(scope) {
99
+ if (scope === 'project') {
100
+ // A trusted project's own skills (`hermes skills trust`).
101
+ return ['.hermes', '.agents'].map((d) => ({ dir: join(process.cwd(), d, 'skills'), tool: 'hermes', source: 'project', skip: hiddenBy([]) }));
102
+ }
103
+ const skip = hiddenBy(names(getKey('skills.disabled')));
104
+ const roots = [join(hermesHome(), 'skills'), ...names(getKey('skills.external_dirs')).map(expand)];
105
+ return roots.flatMap((r) => containers(r)).map((dir) => ({ dir, tool: 'hermes', source: 'user', skip }));
106
+ }
107
+
108
+ // {event: [entries]}; throws (naming the key) when a hook list has an unexpected shape.
109
+ function hookLists() {
110
+ const hooks = getKey('hooks');
111
+ if (hooks !== undefined && hooks !== null && !isObj(hooks)) throw new Error(`${configFile()}: hooks must be a mapping; nothing was changed`);
112
+ const out = {};
113
+ for (const e of EVENTS) {
114
+ const list = hooks?.[e];
115
+ if (list !== undefined && list !== null && !Array.isArray(list)) throw new Error(`${configFile()}: hooks.${e} must be a list; nothing was changed`);
116
+ out[e] = list ?? [];
117
+ }
118
+ return out;
119
+ }
120
+
121
+ // Called before any write: Hermes must be installed and its hook settings must have the expected shape.
122
+ export function checkConfig(scope) {
123
+ if (scope === 'project') return;
124
+ if (!onPath('hermes')) throw new Error('the hermes CLI was not found on PATH; nothing was changed');
125
+ hookLists();
126
+ }
127
+
128
+ export function installHook(scope, command) {
129
+ if (scope === 'project') return { ...NO_PROJECT };
130
+ if (!command.includes(MARK)) throw new Error(`hook command must contain "${MARK}"`);
131
+ const lists = hookLists();
132
+ const todo = EVENTS.filter((e) => {
133
+ const mine = lists[e].filter(ours);
134
+ return !(mine.length === 1 && mine[0].command === command);
135
+ });
136
+ if (!todo.length) return { changed: false };
137
+ const bak = `${configFile()}.bak-skill-autoroute`;
138
+ if (existsSync(configFile()) && !existsSync(bak)) copyFileSync(configFile(), bak);
139
+ for (const e of todo) setKey(`hooks.${e}`, [...lists[e].filter((h) => !ours(h)), { command, timeout: TIMEOUT }]);
140
+ return { changed: true, note: 'Hermes asks once to allow the new hook the next time it starts (or run: hermes hooks list)' };
141
+ }
142
+
143
+ export function removeHook(scope) {
144
+ if (scope === 'project') return { ...NO_PROJECT };
145
+ if (!detect().cli || !detect().configDir) return { changed: false };
146
+ const lists = hookLists();
147
+ let changed = false;
148
+ for (const e of EVENTS) {
149
+ if (!lists[e].some(ours)) continue;
150
+ setKey(`hooks.${e}`, lists[e].filter((h) => !ours(h)));
151
+ changed = true;
152
+ }
153
+ return { changed };
154
+ }
155
+
156
+ export function hasHook() {
157
+ try { return hookLists().pre_llm_call.some(ours); } catch { return false; }
158
+ }
159
+ export const hookConfig = (scope) => (scope === 'project' ? null : configFile());
160
+
161
+ // What Hermes sends a pre_llm_call shell hook, and whether a reply has the shape it reads.
162
+ export const testInput = (text, cwd) => ({ hook_event_name: 'pre_llm_call', session_id: '', cwd, extra: { user_message: text } });
163
+ export const outputOk = (o) => isObj(o) && typeof o.context === 'string';
package/src/triggers.js CHANGED
@@ -13,7 +13,7 @@ const BASE_STOP = 'use when user asks code file files help want wants task work
13
13
  const MORE_STOP = `about ahead after before also any all can each from have how into its more new not only other our out over some
14
14
  such than that them then there these they this those very what which while will your you using used writing write writes
15
15
  building build create add change update error errors handling pattern patterns project projects feature features app apps
16
- need needs like best practice practices guide guidelines skill skills tool tools agent agents claude codex`;
16
+ need needs like best practice practices guide guidelines skill skills tool tools agent agents claude codex hermes`;
17
17
  export const STOP_WORDS = new Set(`${BASE_STOP} ${MORE_STOP}`.split(/\s+/));
18
18
 
19
19
  // R29: a rule that fires on any of these is a catch-all and is dropped.