Repository navigation
Feature Request: Plugin Preference Tabs - Extend SDK for Native Desktop Settings Integration #11494
Description
Overview
AI-authored feature request submitted by Mike Wyant Jr (@mwyant)
This feature request proposes extending the Opencode Desktop SDK to allow plugins to register their own preference tabs/windows in the native Desktop settings interface, enabling plugins to expose configurable settings through the GUI rather than requiring manual file editing.
Problem Statement
Currently, Opencode plugins face several limitations regarding configuration:
- No Native Settings Integration: Plugins cannot add entries to the Desktop settings menu
- Manual Configuration Required: Users must edit configuration files directly
- Limited Discoverability: Plugin settings are hidden and not easily accessible
- No Standardization: Each plugin handles configuration differently
- Poor User Experience: No validation, help text, or dynamic options for plugin settings
Example Case: The small_model configuration exists in opencode.jsonc but can only be set via file editing, with no GUI access or validation of model availability.
Proposed Solution
1. New Plugin SDK Hook: preferences
Extend the plugin SDK with a new preferences hook that allows plugins to register their settings:
interface PreferencesHook {
// Register a preference tab
register: (input: PreferenceRegistration) => Promise<void>;
// Handle preference changes
change?: (input: PreferenceChange) => Promise<void>;
// Validate preference values
validate?: (input: PreferenceValidation) => Promise<ValidationResult>;
}
interface PreferenceRegistration {
id: string; // Unique identifier
title: string; // Display name for tab
icon?: string; // Icon identifier
requiresRestart?: boolean; // Whether changes need restart
schema: PreferenceSchema; // Field definitions
defaults: Record<string, any>; // Default values
ui?: UIPreferences; // UI rendering hints
}2. Desktop Settings Extension
Extend the Desktop application to:
- Dynamic Tab Registration: Allow plugins to add tabs to settings window
- Auto-Generated UI: Render forms from preference schemas
- Real-time Validation: Live validation with error messages
- Provider Integration: Dynamic options from model providers
- Restart Handling: Detect and prompt for restart when needed
3. Preference Schema System
Define a comprehensive schema system for different field types:
interface PreferenceSchema {
[key: string]: {
type: 'string' | 'number' | 'boolean' | 'select' | 'multiselect' | 'file' | 'directory';
description?: string;
default?: any;
validation?: ValidationRule;
options?: Array<{label: string; value: any}>; // For selects
provider?: string; // Dynamic options from providers
help?: string; // Help text for users
};
}Implementation Plan
Phase 1: Core SDK Extension
- Add
preferenceshook to plugin SDK - Implement preference registry in Desktop
- Create basic UI extension points
- Integrate with existing configuration system
Phase 2: Test Case Implementation
Implement the small_model configuration as the test case:
- Plugin that registers a "Small Model" preference tab
- Model selection dropdown with provider integration
- Validation of model availability
- Restart notification on changes
Phase 3: Documentation & Examples
- Plugin development guide for preferences
- Example implementations
- API documentation
- Migration guide for existing plugins
Benefits
- Improved User Experience: Native GUI access to plugin settings
- Better Discoverability: Plugin settings appear in familiar settings interface
- Standardization: Consistent configuration patterns across plugins
- Validation: Real-time validation prevents configuration errors
- Dynamic Options: Plugins can provide context-aware settings
- Professional Integration: Matches Desktop app design patterns
Technical Considerations
Backward Compatibility
- Existing plugins continue to work unchanged
- Preference hook is optional and additive
- Configuration system remains compatible
Security & Validation
- Schema-based validation prevents malformed configurations
- Plugin isolation prevents cross-plugin interference
- Configuration atomicity prevents corruption
Performance
- Lazy loading of preference tabs
- Efficient schema validation
- Minimal overhead for plugins without preferences
Use Cases Beyond Test Case
- Model Configuration: Temperature, max tokens, provider settings
- Theme & UI: Custom themes, font settings, layout preferences
- Integration Settings: API keys, endpoints, timeouts
- Behavioral Settings: Auto-save behavior, notification preferences
- Development Tools: Debug settings, logging levels, feature flags
Success Metrics
- Plugin preference tabs appear in Desktop settings
- Small model selection works with validation
- Model provider integration functions correctly
- Configuration persistence and restart handling
- At least 3 community plugins adopt the new system
Implementation Timeline
- Phase 1: 2-3 weeks (SDK foundation)
- Phase 2: 1-2 weeks (Test case implementation)
- Phase 3: 1 week (Documentation & examples)
Call to Action
This enhancement would significantly improve the plugin ecosystem by providing a standardized, user-friendly way for plugins to expose configurable settings. The small_model configuration serves as an immediate, practical example that would benefit users while demonstrating the system's value.
Please consider this feature request for inclusion in an upcoming release. I'm available to provide use case guidance for UX/UI dev, or can contribute to the development effort via LLM tools. NOTE: I'm an old SysAdmin/DevOps guy, not a coder, so don't trust my code. lol
Technical Details for Implementation Team:
- Repository:
anomalyco/opencode - Focus Area:
packages/desktop/and plugin SDK - Configuration Integration: Existing
opencode.jsoncsystem - UI Framework: Current Desktop app technology stack
- Test Case:
small_modelfield configuration with provider integration
Thank you for considering this enhancement to the Opencode platform!
Activity
github-actions commentedon Jan 31, 2026
This issue might be a duplicate of existing issues. Please check:
Feel free to ignore if your specific use case requires additional features beyond these existing requests.
mwyant commentedon Jan 31, 2026
Addendum: Issue Review and Relationship to Existing Requests
After a comprehensive review of existing issues in the Opencode repository, this feature request stands as a unique and comprehensive solution that addresses multiple related concerns through a systematic approach.
Related Issues Analysis
Issue #8609: "Misleading documentation or incorrect behaviour about small_model"
Issue #10899: "Optimize hot reloading for configuration changes - all modifications require app restart to take effect"
Advantages Over Piecemeal Solutions
Foundation vs. Symptom Fix: This proposal addresses the root architectural limitation (no plugin GUI integration) rather than individual configuration issues
Cross-Platform Benefits: The SDK extensions proposed here would benefit both Desktop and TUI environments, creating consistent configuration experiences across all Opencode interfaces
Scalable Architecture: Establishes patterns that can be reused for future configuration needs beyond small_model
Enhanced Implementation Consideration
Dynamic Refresh Integration:
We recommend incorporating the hot-reloading concepts from issue #10899 as a follow-up enhancement to our proposed preferences system. Specifically:
Cross-Platform Consistency
The proposed SDK extensions should be designed with TUI compatibility in mind:
Conclusion
This feature request represents the most comprehensive solution to the plugin configuration challenge, addressing multiple existing issues through a single, well-architected enhancement that benefits the entire Opencode ecosystem across all platforms.
mwyant commentedon Jan 31, 2026
Phase 1 Complete: Plugin Preference SDK Foundation
✅ Core SDK foundation implemented (Phase 1)
This comment updates the previous automated status post with corrected details and links. Phase 1 delivers the SDK pieces required for plugins to register preference tabs and expose configurable settings to the Desktop (and other clients).
PR (implementation): #11507
Files added (location)
packages/opencode/src/plugin/preferences/types.ts— core interfaces and Zod schemaspackages/opencode/src/plugin/preferences/registry.ts— in-memory registry and lifecycle handlerspackages/opencode/src/plugin/preferences/index.ts— module exportsKey features implemented
string,number,boolean,select,multiselect,file,directoryArchitecture benefits
preferenceshookNext steps (Phase 2+)
If you want, I can now proceed with Phase 2 (UI integration) or add unit tests / docs for the SDK pieces first.
Phase 1: Add plugin preference SDK foundation
Phase 1: Add plugin preference SDK foundation
Phase 1: Add plugin preference SDK foundation
mwyant commentedon Jan 31, 2026
Thanks — I reviewed the issues suggested by the automation and assessed their relationship to this request:
After review:
Recommendation:
I can update the issue labels and references if you want. Otherwise I will continue with Phase 2 (Desktop UI) once you confirm the preferred approach.
mwyant commentedon Jan 31, 2026
Update: progress, docs, tests, and next steps
Thanks everyone — quick update on where we are and the plan forward. TL;DR: Phase 1 (SDK) is implemented, Phase 2 server + minimal UI wiring is in the branch, unit tests added, and docs updated. Feedback welcome.
What I shipped (branch:
mwyant/feature/plugin-preference-tabs-upstream):/preferencesand a minimal SolidJS Settings tab that lists plugin tabs and calls validate/apply endpointsopencode.jsoncunderplugin_preferences.<pluginId>.<key>packages/plugin/examples/small-model-plugin.ts(register + validate + change handlers)packages/opencode/test/preferences.registry.test.ts) — passing locallypackages/opencode/docs/plugin-preferences.mdupdated with next steps, vision, and local testing notestools/proofreader.js+agents/proofreader.mdto avoid literal escaped-newline issues in automated commentsQuick runtime note
react/jsx-dev-runtime) — I addedreactto the opencode package to resolve that. The server now starts (listening at http://127.0.0.1:4096 for local runs). If your instance requires auth, you may see "Unauthorized" until run with the right flags.Next steps (proposed & planned)
applyPreferenceChangewriting toopencode.jsoncin a temp project directory (I can add these next).Questions for maintainers & reviewers
plugin_preferences.<pluginId>.<key>) or mapping certain plugin preferences directly to top-level config keys (e.g.,small_model)? I recommend namespaced by default to avoid collisions and offer a migration helper for cases that want flat fields.validateendpoint per-field or validate whole-tab payloads at once? Current approach validates per-field sequentially (simple & incrementally friendly).Request: please review PR #11507 and the Phase 2 files on the branch. I'm ready to iterate per reviewer feedback. If folks prefer, I can open a draft PR specifically for Phase 2 UI work to keep review focused.
Thanks — looking forward to feedback and willing to adjust priorities.
github-actions commentedon Apr 2, 2026
To stay organized issues are automatically closed after 90 days of no activity. If the issue is still relevant please open a new one.