Skip to content

[FEATURE]: add OPENCODE_DISABLE_GLOBAL_CONFIG flag to skip global config loading #21264

@ZY-Yim

Description

@ZY-Yim

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

When embedding OpenCode as a subprocess via opencode serve (e.g. in an Electron app or backend service), the host application
provides all configuration through OPENCODE_CONFIG_CONTENT. However, OpenCode still loads global config files and scans global
directories from ~/.config/opencode/, which can cause unexpected behavior by merging unrelated user-level settings, agents, skills,
and plugins into the intended configuration.

Currently there is no way to skip global config and directory scanning:

  • OPENCODE_DISABLE_PROJECT_CONFIG only skips project-level config, not global
  • OPENCODE_CONFIG_CONTENT is additive — it merges on top of global config rather than replacing it

Note: This is related to but different from #20784 (settingSources). That PR provides a granular SDK-level mechanism to control
config sources. This PR takes a simpler approach with a single env var flag, consistent with existing OPENCODE_DISABLE_*
conventions, specifically targeting the embedded opencode serve use case.

Proposed Solution

Add a new environment variable OPENCODE_DISABLE_GLOBAL_CONFIG. When set to 1 or true:

  1. loadGlobal() in config.ts returns an empty config object, skipping all files under ~/.config/opencode/ (config.json,
    opencode.json, opencode.jsonc)
  2. ConfigPaths.directories() in paths.ts excludes ~/.config/opencode/ from the returned list, preventing scanning of global
    agents, skills, commands, and plugins

Scope

  • Skipped: ~/.config/opencode/ config files, agents, skills, commands, plugins
  • Not affected: project-level .opencode/ directories, OPENCODE_CONFIG, OPENCODE_CONFIG_CONTENT, well-known, account, managed
    configs

Naming

Follows the existing OPENCODE_DISABLE_* convention (e.g. OPENCODE_DISABLE_PROJECT_CONFIG, OPENCODE_DISABLE_CLAUDE_CODE).

Use Case

// Electron app spawning opencode serve
spawn(binaryPath, ['serve', '--port', '4096'], {
  env: {
    OPENCODE_DISABLE_GLOBAL_CONFIG: '1',
    OPENCODE_DISABLE_CLAUDE_CODE: '1',
    OPENCODE_CONFIG_CONTENT: JSON.stringify(myConfig),
  },
})

Implementation

Minimal change  3 files, +15 lines:
- packages/opencode/src/flag/flag.ts: declare flag + dynamic getter
- packages/opencode/src/config/config.ts: early return in loadGlobal()
- packages/opencode/src/config/paths.ts: exclude global directory from ConfigPaths.directories()

PR: #21650

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type
No fields configured for issues without a type.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions