[FEATURE]: support config.d/ directory for modular configuration

[ferdinandyb]

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

Problem

Currently, all OpenCode configuration must be in a single opencode.json file. This becomes unwieldy when managing complex setups with many providers, MCP servers, permissions, and custom settings. Users cannot easily:

• Share partial configurations across machines (e.g., just permissions or just theme)
• Keep sensitive configuration separate from version-controlled settings
• Organize configuration logically by concern (providers, permissions, plugins, etc.)
• Manage large sections of granular permissions across multiple files (e.g., 10-permissions-git.json, 11-permissions-test-tools.json, 12-permissions-deploy.json)

Proposed Solution

Add support for a config.d/ directory that allows splitting configuration into multiple files:

• ~/.config/opencode/config.d/ for global configuration fragments
• .opencode/config.d/ for project-specific fragments

Files would be loaded alphabetically and merged after the main config file, following the common Unix pattern (similar to /etc/sudoers.d/, /etc/apt/sources.list.d/, etc.).

Use Cases

• Granular permissions: Split permissions by tool category (10-permissions-git.json, 11-permissions-test-tools.json, 12-permissions-deploy.json)
• Plugin organization: Maintain 50-plugins.json for all plugin definitions
• Sensitive data: Store API keys in a non-versioned fragment file
• Shared configs: Symlink common fragments across projects

[github-actions]

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

• [FEATURE]: Composable configs #8241: [FEATURE]: Composable configs - Proposes extending config from other sources (local paths, git repos)
• [FEATURE]: Plugin Hook for Registering Additional Config Directories #6347: [FEATURE]: Plugin Hook for Registering Additional Config Directories - Requests ability for plugins to register additional config directories for skills, agents, commands, and tools
• [FEATURE]: Allow custom skills directories #8533: [FEATURE]: Allow custom skills directories - Requests custom skills directories via config
• Reorganize and document dirs for config, agents, auth credentials, sessions #4170: Reorganize and document dirs for config, agents, auth credentials, sessions - Discusses config directory organization and structure

Feel free to ignore if #9062 addresses your specific needs differently (such as the config.d/ pattern specifically).

[ferdinandyb]

I think my PR for this problem has broken due to updates. But I've been thinking, that the config.d solution is great for breaking up opencode.json, which is already great. But it does not allow sharing configuration options between agents.

Case in point this is one of my agents and this is my opencode.jsonc. My config philosophy is that opencode should be allowed to do anything that is more-or-less read only and asks for anything else. Obviously, I have a growing list of standard unix tools in the allow list, that I would like to share with almost all of my agents, since in general there is no problems with them reading stuff.

The biggest problem here is that this actually requires that agents also merge some other files. So I could imagine that we go forward with config.d which is loaded completely by the main agent, but that sub-agents reference them.

Hmm, in that case it would probably be better if the configuration in general got an extra option, which is a list, where you can list other jsonc files that are merged with the current config (probably supporting glob would be great). So your main config could say something like

{
mergeconfigs = ["config.d/*"]
}

while a subagent could go

{
mergeconfigs = ["config.d/unixtools.jsonc", "config.d/foo.jsonc"]
}

[3x3cut0r]

I am also in favor of conf.d logic. Why?
For security reasons alone.
Although I generally believe that agents should be allowed to read everything, there are exceptions. For example, *.env, *credential, or even tool calls such as "docker inspect *". And these can also be folder/project specific. Security confs could be shared separately. This is not currwntly feasible.

[aspiers]

Yes please, this is a much-needed feature!

For all the same reasons it's such a popular pattern elsewhere, this would be very helpful in OpenCode too. There are multiple use cases both for global and per-project config, e.g.

• Have one main config file tracked in git, then allow local per-machine overrides which can be git-ignored:
  • Keep MCP API tokens out of git
  • Override default bash permission of ask with allow on a sandbox machine
  • Install an extra plugin only on one machine
• Allow global config to be constructed from multiple git repos via GNU Stow
• Avoid massive config files