[FEATURE]: Support multiple custom config directories #26051

Feature hasn't been suggested before.

• I have verified this feature I'm about to request hasn't been suggested before.

Describe the enhancement you want to request

Support multiple custom config directories

I’d like to propose adding support for multiple custom config directories.

Currently, opencode supports OPENCODE_CONFIG_DIR, which allows loading one custom .opencode-like directory. This works well for a single external config source, but it makes composition difficult when configuration is split across multiple reusable local sources.

Example workspace:

workspace/
  agents/
    backend/.opencode/
    frontend/.opencode/
    reviewer/.opencode/

Each of these directories may contain its own agents, commands, modes, plugins, tools, and config files.

Today, the workaround is to generate a synthetic .opencode directory with copied files or symlinks. It would be cleaner if opencode could load several local config directories directly.

Suggested behavior

Add a new environment variable:

OPENCODE_CONFIG_DIRS="/path/to/backend/.opencode:/path/to/frontend/.opencode" opencode

On Windows, it should use the platform delimiter:

$env:OPENCODE_CONFIG_DIRS="C:\backend\.opencode;C:\frontend\.opencode"
opencode

OPENCODE_CONFIG_DIR should remain supported and unchanged for backwards compatibility.

If both are set, the load order could be:

existing global/project/home config dirs
→ OPENCODE_CONFIG_DIR
→ OPENCODE_CONFIG_DIRS entries

Use cases

This would make it easier to compose opencode configuration from multiple reusable local sources, for example:

• shared team agent packs
• reusable command/plugin collections
• workspace setups composed from several cloned repositories
• monorepo-like setups where different packages expose their own .opencode directories

Related issues

I found related proposals around modular configuration, but I did not find one specifically about loading multiple custom config directories.

Related: #9062 proposes a config.d/ directory for splitting configuration into multiple files. This proposal is different: it is about loading multiple local .opencode-like directories, not splitting one config directory into multiple JSON fragments.

Non-goals

This proposal is not about:

• cloning repositories
• fetching remote configs
• package management
• automatic workspace scanning
• dynamic config reload

It would only allow opencode to load config from multiple local directories that already exist on disk.

Notes

From looking at the code, the config loader already appears to work with an ordered list of config directories. This change would expose a way to append multiple custom directories without changing the existing config loading model.

Would this be something you’d be open to supporting?