Feature Request: Plugin shutdown hook for graceful cleanup

[ErcinDedeoglu]

Summary

Add a shutdown/exit hook to the plugin system so plugins can perform cleanup operations before OpenCode exits.

Use Case

I'm developing opencode-sync, a plugin that syncs OpenCode data (sessions, messages, config, etc.) to a private GitHub repository.

The plugin needs to sync local changes to remote before exit to prevent data loss. Currently, there's no way for plugins to:

1. Know when OpenCode is about to exit
2. Perform async cleanup operations before process termination

Current Behavior

Looking at the source:

• packages/plugin/src/index.ts - The Hooks interface only has event hook for Bus events
• packages/opencode/src/cli/cmd/tui/thread.ts - Has onExit callback but it's internal, not exposed to plugins
• Session events are Created, Updated, Deleted, Diff, Error - no shutdown event

When OpenCode exits (Ctrl+C, :q, etc.), plugins have no opportunity to run cleanup code.

Proposed Solution

Add a shutdown hook to the plugin Hooks interface:

export interface Hooks {
  event?(input: { event: Bus.Event }): void;
  shutdown?(): Promise<void>;  // New hook
}

The shutdown hook should:

1. Be called before OpenCode terminates
2. Support async operations (return Promise)
3. Have a reasonable timeout (e.g., 5 seconds) to prevent hanging

Alternatives Considered

1. Node.js process events (beforeExit, SIGINT, SIGTERM) - OpenCode intercepts signals before plugin handlers run
2. Frequent background syncing - Works but can't guarantee final changes are synced
3. File watching with debounce - Same limitation, final changes may be lost

Additional Context

This would enable plugins to:

• Sync data to remote storage
• Close database connections
• Flush logs
• Clean up temporary files
• Save state

Thank you for considering this feature!

[github-actions]

This issue might be a duplicate of existing issues. Please check:

• [FEATURE]: Add shutdown/exit event allowing a plugin to right before closing. #10003: Add shutdown/exit event allowing a plugin to run before closing (direct duplicate)
• Memory leak: Instance disposal doesn't clean up plugins or cached resources #9157: Memory leak: Instance disposal doesn't clean up plugins or cached resources (requests dispose() hook for cleanup)
• Windows: Ghost port bindings when server killed via SIGTERM (affects plugins like openralph) #9859: Windows: Ghost port bindings when server killed via SIGTERM (related signal handling for graceful shutdown)
• Memory leak: Uncleaned timeouts, intervals, and subscriptions #9156: Memory leak: Uncleaned timeouts, intervals, and subscriptions (related resource cleanup needs)
• [FEATURE]: SessionStart hook for session lifecycle events #5409: SessionStart hook for session lifecycle events (related plugin lifecycle hook requests)
• [FEATURE]: Plugin Hook for Instant TUI Commands #5305: Plugin Hook for Instant TUI Commands (related plugin system extensibility)
• [FEATURE]: Finish hook, when LLM is ready to get new instructions #5515: Finish hook, when LLM is ready to get new instructions (related lifecycle hook requests)

Feel free to ignore if none of these address your specific case.

[RKelln]

I use beads (https://github.com/anomalyco/beads) for issue tracking, which embeds a Dolt SQL server for its local database. Beads 0.59+ manages the Dolt server lifecycle automatically (auto-start on first bd command, stop via bd dolt stop).
When OpenCode exits — even a normal Ctrl+C or :q — I'd like to stop the dolt server.

This affects anyone using OpenCode with an embedded database (Dolt, SQLite WAL, etc.) that requires graceful shutdown for data integrity.

Added (Opus written) PR for this:
RKelln:feat/plugin-shutdown-hook

[andrewstackme]

what is the timeline for resolution?

[jtackaberry]

Running into this as well just building a small custom plugin to improve tmux integration. I need to be able to clear some tmux pane/window variables on exit. I'm resorting to a tragic hack at the moment (which only happens to work because cleanup activities can be done outside of opencode), so a proper shutdown hook would be very much appreciated.

[rekram1-node]

There is an instance dispose hook now