feat: hot-reload skills, commands, agents and config on file change

[mccaffrey-jonathan]

Issue for this PR

Closes #8751

Type of change

• New feature

What does this PR do?

Opt-in hot reload behind OPENCODE_EXPERIMENTAL_HOT_RELOAD=true.

• The filesystem watcher additionally subscribes config directories (global config dir and .opencode dirs from config entries), so changes there emit file.watcher.updated even when the whole-project watcher is off.
• A new HotReload service, armed by InstanceStore after each boot, listens for those events, filters to config-relevant paths (files under config/skill directories, opencode.json[c] anywhere), debounces 200ms, then reloads through the existing InstanceStore.reload and invalidates the v2 location-service layer so both stacks reread disk state.
• Clients already re-sync on server.instance.disposed; the TUI additionally refreshes its v2 agent/command/skill stores on that event.
• Plugin install artifacts (package.json, lockfiles) inside config dirs are ignored to avoid reload loops.

This is also one answer to the QUESTION(Dax) comment in packages/core/src/skill.ts: the reload policy here is "drop the location layer on watch events" rather than per-cache invalidation.

Known limitations: file events landing in the short window between dispose and re-arm are missed; external skill directories are watched only once discovered (each reload re-discovers); the watcher arms when v2 location services build, which every TUI/desktop/web client does immediately.

How did you verify your code works?

End to end on Windows with opencode serve and the flag set, while the server was running:

• added a new skill directory — appears in /skill and /api/skill without restart
• edited a skill description — updated in the list
• added .opencode/command/hotcmd.md — appears in /command
• observed server.instance.disposed on the /event SSE stream on each reload
• confirmed a single debounced reload per change, no reload loop

Tests:

• packages/core: new watcher test "watches config directories when hot reload is enabled" (flag on, non-git root — config-dir events fire, project files stay unwatched)
• packages/opencode: unit tests for the relevance filter (config dirs, opencode.json anywhere, lockfile exclusions, prefix-sibling edge case)
• typecheck clean in core/opencode/tui; packages/opencode config suite (191 tests) passes; the one failure in test/project/instance-bootstrap.test.ts reproduces identically on a clean dev checkout on this machine (environment-related, not from this change)

Built and tested with Claude assistance; I reviewed and verified the changes.

Checklist

• I have tested my changes locally
• I have not included unrelated changes in this PR

[github-actions]

Hey! Your PR title Hot reload doesn't follow conventional commit format.

Please update it to start with one of:

• feat: or feat(scope): new feature
• fix: or fix(scope): bug fix
• docs: or docs(scope): documentation changes
• chore: or chore(scope): maintenance tasks
• refactor: or refactor(scope): code refactoring
• test: or test(scope): adding or updating tests

Where scope is the package name (e.g., app, desktop, opencode).

See CONTRIBUTING.md for details.

[github-actions]

The following comment was made by an LLM, it may be inaccurate:

Based on my search results, I found a potentially related PR:

Related PR:

• feat(opencode): add reload_config agent tool with auto-resume #43458 - feat(opencode): add /reload slash command with auto-resume - This PR adds reload functionality with auto-resume capabilities, which may overlap with or be related to the hot reload feature in PR feat: hot-reload skills, commands, agents and config on file change #43538.

Also note:

• fix(opencode): defer config reload until sessions are idle #42622 - fix(opencode): defer config reload until sessions are idle - This handles config reloading behavior and might be relevant to hot reload implementation.
• fix(server): preserve directory events across reloads #42632 - fix(server): preserve directory events across reloads - Related to reload behavior in the server.

The most likely duplicate or related work is PR #43458, which already implements a reload command. You should verify if this PR #43538 is addressing a different aspect of reloading or if it duplicates that functionality.

[github-actions]

Thanks for updating your PR! It now meets our contributing guidelines. 👍

[github-actions]

Automated PR Cleanup

Thank you for contributing to opencode.

Due to the high volume of PRs from users and AI agents, we periodically close older PRs using automated criteria so maintainers can focus review time on the most active and community-supported contributions.

This PR was closed because it matched the following cleanup criteria:

• The PR was created more than 1 month ago
• The PR had fewer than 2 positive reactions
• Positive reactions are counted as thumbs-up, heart, celebration, or rocket reactions on the PR

PRs created within the last month are not affected by this cleanup.

If you believe this PR was closed incorrectly, or if you are still actively working on it, please leave a comment explaining why it should be reopened. A maintainer can review and reopen it if appropriate.

Thanks again for taking the time to contribute.