Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

perf(hooks): SessionStart p95 7.1 s from about 26 per-plugin prerequisites rows; use one shared async runner

Open
  • Is something wrong?
#6,633 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
35/100
Issue type
Refactor
Clarity
Mostly clear
Activity status
Active
Tech stack
json, powershell, shell
Domain
developer-experience

Research direction

Start with the SessionStart row in plugins/harness-ops/hooks/hooks.json (around lines 507-526) and the shared lib/prerequisites.sh and lib/prerequisites.ps1, including the notice latch at lines 15-40 of prerequisites.sh. First settle the PPID discrepancy by checking which half of the row runs under a Claude Code hook launch. Done means one combined SessionStart runner replaces the per-plugin rows, grep -l prerequisites.ps1 plugins/*/hooks/hooks.json returns 0 or 1, and a session without node shows one notice.

Written by the indexing model from the issue text.

Description

needs-human needs-triage

Related: #6244 (Windows performance audit tracker), #6251 (matcher fix, closed), #6130 (node-notice exit 127), #4373 (hook fan-out umbrella).

Problem

Every plugin that needs a prerequisite check registers its own SessionStart row. 26 hooks.json files carry a prerequisites.sh / prerequisites.ps1 node-notice row, and 8 formatter plugins add a prerequisites.mjs probe row. Each row starts its own process tree, and SessionStart gates the first response. The hooks docs say: "SessionStart runs on every session, so keep these hooks fast" (https://code.claude.com/docs/en/hooks#sessionstart).

Measured

Method: OTEL hook_execution_complete.total_duration_ms for SessionStart on the windows lane (melo-desk-001), plus direct timing of one row on the same host (date +%s%N around the command, 3 runs).

what value
SessionStart wall-clock, p95 7.1 s (go-faster run 20261008T152359Z, hooks area)
plugin SessionStart rows with a prerequisites check 26 hooks.json files (grep -l prerequisites.ps1 plugins/*/hooks/hooks.json)
powershell -NoProfile -ExecutionPolicy Bypass -File lib/prerequisites.ps1 node-notice ... alone 196 / 158 / 158 ms
sh lib/prerequisites.sh node-notice ... alone 31 / 30 ms
the whole row as written, run under bash -c 52 / 50 / 49 ms
bare node -e 0 / bare bash -c true 52 ms / 29 ms

Discrepancy to settle first: the row is sh prerequisites.sh node-notice ...; ${PPID:+exit}; powershell ... prerequisites.ps1 .... Under Git Bash PPID is set, so the row exits before the PowerShell half and costs about 50 ms, not about 150 ms. The reported ~147 ms per row (22 plugins) applies only where the PowerShell half runs, which is the #6130 case (/bin/sh is not bash). Confirm which half runs inside Claude Code hook launches on this host (a debug log of one startup shows it) before sizing the saving.

Either way the rows are ~26 separate process launches that each answer the same question (is node on PATH), and they run before the first response.

Where

Example (plugins/harness-ops/hooks/hooks.json:507-526, same shape in 25 other plugins, e.g. plugins/eol-normalizer/hooks/hooks.json, plugins/actionlint/hooks/hooks.json:57):

"command": "sh \"${CLAUDE_PLUGIN_ROOT}/lib/prerequisites.sh\" node-notice /harness-ops:check; ${PPID:+exit}; powershell -NoProfile -ExecutionPolicy Bypass -File \"${CLAUDE_PLUGIN_ROOT}/lib/prerequisites.ps1\" node-notice /harness-ops:check",
"timeout": 10

Files with the row: actionlint, animation, autonomy, bash-format, biome-format, context-budget, context-guard, desktop-notification, discovery, disk-hygiene, eol-normalizer, explainer-video, go-format, guardrails, harness-ops, instruction-placement, markdown-format, multi-agent, powershell-format, rate-limit-guard, ruff-format, session-flow, source-control, speech, testing, typos-format.

Proposed fix

  1. One shared prerequisites runner: a single SessionStart row (in one always-enabled plugin, for example harness-ops) that checks node once and the per-plugin binaries from each plugin's prerequisites.json, and prints one combined notice. The per-plugin rows are then removed.
  2. Mark that one row "async": true. The prerequisites notice is advisory and carries no decision, so it loses nothing by arriving on the next turn.

Basis: async hooks run "in the background without blocking Claude", cannot block or return decisions, and are not subject to timeout once running; output is delivered on the next conversation turn (https://code.claude.com/docs/en/hooks#run-hooks-in-the-background, Limitations: "Each execution creates a separate background process. There is no deduplication across multiple firings"). Basis for keeping the row cheap: https://code.claude.com/docs/en/hooks#sessionstart.

Risk to check: a plugin that disables itself without node (the notice's job) must still surface the warning once; the notice latch (lib/prerequisites.sh:15-40) has to move into the shared runner.

Expected saving

Start-up process count drops from about 26 to 1 (plus the 8 formatter probes folded in). If the PowerShell half runs on the affected hosts: about 22 x 147 ms of CPU removed, and the 7.1 s p95 should fall by whatever share the rows hold on the critical path (hooks run in parallel, so the p95 improves through less contention rather than a sum). Where the half is skipped: about 26 x 50 ms of CPU. The wall-clock saving needs the after-measurement below.

Verify after the fix

  • grep -l 'prerequisites.ps1' plugins/*/hooks/hooks.json | wc -l returns 0 (or 1 for the runner).
  • /harness-ops:observability latency SessionStart p50/p95 over at least 100 fires before and after (OTEL hook_execution_complete, event SessionStart).
  • Kill node from PATH in a test session: one combined notice appears, once per session.
Dominant language
Shell
Stars
22
Forks
2
Avg merge
6h 42m
Merged PRs (30d)
902

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from melodic-software/claude-code-plugins

All issues in melodic-software/claude-code-plugins

Similar issues

More Shell/Bash issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.