Skip to content

fix(watchers): debounce skills and settings reload bursts - #1370

Merged
kevincodex1 merged 1 commit into
Twigpine:mainfrom
chioarub:fix/watchers-debounce-reload-bursts
May 26, 2026
Merged

kevincodex1 merged 1 commit into
Twigpine:mainfrom
chioarub:fix/watchers-debounce-reload-bursts

Conversation

@chioarub

@chioarub chioarub commented May 26, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Fixes #1366.

  • Debounce skills reload bursts so folder moves and renames produce one reload instead of repeated immediate reload work.
  • Add a skills reload cooldown to avoid back-to-back reload cascades during multi-wave chokidar bursts.
  • Remove redundant direct skill cache clearing because clearCommandsCache() already clears skill caches.
  • Debounce settings filesystem fanout so bursty settings events produce one cache reset and one listener notification batch per source.
  • Harden cleanup paths so pending timers and late async callbacks do not run after disposal/reset.

Why

External file operations can produce many chokidar events in a short period. Before this change, those events could repeatedly run ConfigChange hooks, invalidate caches, re-read disk, and notify React listeners, which could saturate the UI thread and make OpenClaude appear frozen.

Implementation notes

  • Skills changes still pass through ConfigChange hooks before cache clearing and notification.
  • Blocking ConfigChange hooks still prevent skills reloads and settings fanout.
  • Skills reloads now serialize in-flight hook work and defer cache clearing if newer events arrive before hooks finish.
  • Settings fanout tracks per-source generations so stale accepted changes cannot emit after newer same-source events are blocked or pending.
  • Programmatic notifyChange() and MDM polling keep immediate fanout behavior; only filesystem watcher fanout is debounced.
  • Regression tests use explicit dependency overrides instead of mock.module(...) so the serialized Bun suite does not leak mocks into later test files.

Testing

  • GitHub Actions smoke-and-tests passed: bun run smoke, bun test --max-concurrency=1, Python tests, PR intent scan, provider tests, provider recommendation tests.
  • GitHub Actions web passed: web typecheck and build.
  • Local: bun test src/utils/skills src/utils/settings
  • Local: bun test --max-concurrency=1 src/utils/skills/skillChangeDetector.test.ts src/utils/plugins/pluginLoader.test.ts src/utils/settings/changeDetector.test.ts src/tools/BashTool/bashPermissions.test.ts
  • Local: bun run build
  • Local: git diff --check

Manual validation

  • Started OpenClaude with an isolated CLAUDE_CONFIG_DIR and a dummy skills/dummy-skill/SKILL.md fixture.
  • Externally renamed/moved the dummy skills folder in a burst and edited SKILL.md.
  • Confirmed the skills burst produced one ConfigChange:skills hook/reload in the debug log.
  • Confirmed the TUI remained responsive after watcher bursts by sending input and receiving the normal Ctrl-C exit prompt.
  • Repeated with a settings file change/delete-recreate burst and confirmed one Settings changed from userSettings app-state update in the debug log.

@chioarub
chioarub force-pushed the fix/watchers-debounce-reload-bursts branch from 2cc5cd8 to ca3c62b Compare May 26, 2026 08:38
@chioarub
chioarub marked this pull request as ready for review May 26, 2026 08:50
@kevincodex1
kevincodex1 merged commit ed91673 into Twigpine:main May 26, 2026
2 checks passed
discopops pushed a commit to discopops/openclaude that referenced this pull request May 28, 2026
Gravirei added a commit to Gravirei/openclaude that referenced this pull request May 28, 2026
- fix(autocompact): retry circuit breaker after cooldown (Twigpine#1375)
- fix(provider): require API key input when adding OpenGateway (Twigpine#1384)
- fix(provider): allow remote Ollama without OPENAI_API_KEY (Twigpine#952)
- fix(codex-stream): recover tool args delivered only via done events (Twigpine#1262)
- fix: route MiniMax compacting through Anthropic-compatible API (Twigpine#1154)
- fix(thinking): disable thinking for unsupported Ollama models (Twigpine#1376)
- feat(agents): set active session agent from agents menu (Twigpine#1349)
- fix(repl): show permission prompts while draft input is present (Twigpine#1393)
- fix(model): include profile models in descriptor picker (Twigpine#1361)
- Improve warning notice formatting (Twigpine#1415)
- fix(codex): allow credential storage fallback (Twigpine#1347)
- fix(attribution): make git attribution opt-in by default (Twigpine#1335)
- fix(agent): allow custom model overrides (Twigpine#1337)
- feat(query): robust multi-lingual and structural continuation nudge (Twigpine#1280)
- fix(watchers): debounce skills and settings reload bursts (Twigpine#1370)
- feat: configure API retry backoff (Twigpine#370) (Twigpine#1095)
- chore(main): release 0.15.0 (Twigpine#1325)
- ci: retrigger CodeQL after action download outage (Twigpine#1374)
- Fix launcher heap setup for long sessions (Twigpine#1242)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

OpenClaude freezes on external changes to skills/settings directories

2 participants