Repository navigation
[FEATURE]: Multiple opencode.json inside a project with documentation and git recommendation for privacy / security #61099
Description
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
Hello,
I would want to share my opencode configuration inside projects, because it make sense to share some of the settings to others users, for example :
- Plugin cofiguration
- Public mcp configurations
- Some minimal provider settings and tooling
- Watcher ignore glob path
- Default permissions to add some reviewed and approved commands inside projects
- Some static paths to installation folder or specific path needs
Etc.
But there is also some configuration I don't want to share, specific per project (so global config can't help):
- Some local tools or permissions bound to myself specific to a project
- Some sensitive informations like api key, secrets, environment variables, or global paths to local resources or other projects external directory.
- Some specific configuration for models and providers linked to my own usage (not global and specific to project).
- Some experiments or unproved tooling to test agentic workflows
My point is, opencode.json(c) is tricky to share, but could now be some useful for minimal configuration like AGENTS.md or agents/skills used inside a project.
I have seen in documentation about opencode config can be read from others location than root project like .opencode/opencode.json(c) (https://opencode.ai/v2/docs/policies#precedence) or /home/user/projects/acme/packages/web/opencode.json (https://opencode.ai/v2/docs/config/#locations), but it seems it lacks what should be used and shared for a project, or what strategies can be done.
And also documentation say to run either from /home/user/projects/acme/packages/web (override case), or either choose root project or .opencode/ location, NOT about having both config at the same time, one private (.opencode/) gitignored and one public in root project.
My recommended solution would be to read both root project and .opencode/opencode.json(c) location, with local having priority to root project. Policies applied in revert order of permissions for denying permissions of local configuration should be noted as an important point with this solution.
Others solutions could be to add instructions in root project like an include_config with same strategy, but don't seems to make sense to add a new keyword used in others opencode.json like global config.
Activity
opencodejr commentedon Nov 1, 2026
Thanks for the detailed write-up! You're asking for a supported, documented way to commit a shared project config while keeping a private, per-project config (secrets, personal tools and permissions, experiments) out of git.
In v2 most of this already works. For each directory, OpenCode loads both the root
opencode.json(c)and.opencode/opencode.json(c)and merges them:.opencode/opencode.json(c)overrides the root file. You can commitopencode.jsonand add.opencode/opencode.json*to.gitignorefor your private overrides. If you also commit agents or skills under.opencode/, ignore only the config file, not the whole folder..opencode/opencode.json(c). Your private file can add restrictions but can't re-allow something the shared config denies.You're right that the config locations docs don't describe this shared plus private pattern, or the reversed policy precedence for it. Maintainers will consider documenting it and whether to add any further support.
Related issues and PRs:
opencode.local.jsonfor project-local config overrides #17232: earlier request for anopencode.local.jsonlocal override fileextendssupport inopencode.json