No opencode.json file

Description

I've installed opencode in mac and linux WSL... and I'm unable to find the file opencode.json is not in ~/.config/opencode/ where it supposed to be according the documentation, in fact is nowhere in the hard drive.

However, it remembers my theme selection, so that is saved somewhere... but where?

OpenCode version

1.0.55

Steps to reproduce

Install opencode (brew or npm)
Try to find the opencode.json file

Screenshot and/or share link

Operating System

macOS, Debian 12 and Windows 11

Terminal

terminal (mac), windows terminal (wsl)

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

opencode.json/config.json search path #3407: Similar confusion about opencode.json/config.json search paths and file locations
PATCH /config uses wrong config file #4194: PATCH /config uses wrong config file - related to config file path issues
Reorganize and document dirs for config, agents, auth credentials, sessions #4170: Documentation issue about reorganizing config directories

Feel free to ignore if none of these address your specific case.

@agarzon

@agarzon the opencode.json needs to be created by u the user, the state of the tui is saved in ~/.local/state/opencode

for theme thats in ~/.local/state/opencode/kv.json

I see, the documentation then is quite confusing.

@agarzon

@agarzon do we need to make it more clear here that by "Place your config" we mean create it?

https://opencode.ai/docs/config/#global

Which part confused you so we can update

The ~/.local/state/opencode for instance, it is not mentioned in the documentation.

@agarzon

@agarzon well thats not a file you should be editing but we can document the various paths thats fair

For what it's worth, I got caught up by this as well. I'm a bit more accustomed to apps writing back to their configuration file. Typically, they dump out a file with default values and then change values as configured in the GUI/TUI. I'm trying to consistently set up my development environment with Home Manager, so I thought the simplest thing would be to configure OpenCode from within the program and then extract the configuration over to my Home Manager config. In general, I find this approach a lot easier to follow when getting started than trying to compose a config file from a bunch of documentation snippets in an application I've never successfully configured before.

In any event, I spent a fair bit of time trying to figure out where everything was. The docs and, consequently, search engines indicated config would be in a place that it ultimately wasn't being written to. Without a doubt, I assumed the configuration file would be updated and that's not guaranteed behavior, but the assumption was based on how other tools typically work. I was about to dig into the source, but I ultimately worked it out by changing the theme and then grepping on the theme value until I discovered ~/.local/state/opencode.

Maybe an opencode /init_config would be interesting? That way OpenCode wouldn't have to write back to config.json but

same confusion, the docs says a lot about opencode.json, but never guide how to start from the first time.

Same here.

I'm consolidating various dotfiles and similar settings.json files into a single repository, managed by chezmoi.
I was expecting that changing to/setting a specific model via TUI would write that to ~/.config/opencode.json so I could just lift it from there, but it obviously doesn't — when that would be the expected behaviour based on both the official documentation and past experience with other tools.

It makes it quite difficult to get a proper understanding of the specific syntax to be used in the settings file.
For example, what's the correct syntax to add to opencode.json to get OpenCode to use "Claude Opus 4.5 (latest)" (as shown on the TUI)? Should it be claude-opus-4-5 or claude-opus-4-5-latest? Or maybe something else?

Just "dumping" the configuration from the TUI back into opencode.json (or, in general, OPENCODE_CONFIG) would be a great improvement.

Coming from codex I have to say the config seems to be a bit of a mess. I am on Windows and in my home directory after starting opencode once, I now have:

C:\Users\<USER>\
  -> .config\opencode\
      -> node_modules\
      -> package.json
      -> bun.lock
      -> .gitignore
  -> .local
      -> state\opencode\
           -> kv.json
      -> share\opencode\
           -> log
           -> storage
           -> bin
           -> auth.json

Why would opencode create all these files under .config\opencode\ if it has its "internal" state dir at .local\state.
When I create an opencode.jsonc file under C:\Users<USER>.config\opencode\opencode.jsonc file it does not get picked up.
The opencode UI does not show which files it effectively is loading from where. And by reading the documentation it is not clear where opencode "magically" stores the model authentications or any settings interactively applied via the UI like changing the theme.

All this leaves one very puzzled.

The configs are an absolute mess. I've never seen a case where the most important user configuration file is not even created by default. Instead once has to figure out what the syntax is to create it properly. That I shouldn't be "touching" certain files is not a reason to scatter them all over my disk.

Well, i'm glad i'm not the only one who noticed the mess with that approach 😁

It makes it impossible to share configurations when you have opencode installed in different machines (mac vs linux vs windows) like my case where I use the dotfile approach and syncthing.

I hope the author can reconsider that structure and do what others CLI's are doing.

I agree this is confusing behavior.

One question from me. Why is this not part of the opencode.json?

$ cat "$XDG_STATE_HOME/opencode/kv.json"
{
  "theme": "opencode",
  "tips_hidden": true,
  "animations_enabled": true,
  "sidebar": "auto",
  "thinking_visibility": true,
  "timestamps": "show",
  "tool_details_visibility": true,
  "assistant_metadata_visibility": true,
  "scrollbar_visible": false,
  "header_visible": false,
  "diff_wrap_mode": "word"
}⏎

As a user of the Windows desktop client, I have been troubled by the same issue. I purchased an AliCloud Coding Plan, but there is no official support for it in the provider settings, so I had to configure it manually. However, after connecting, an error occurred: invalid access token or token expired.
I wanted to find the configuration details to verify its correctness, but under Connected Providers, there is only a Disconnect option—there are no view or edit options at all.
I then tried to locate the opencode.json file to check and modify it, but I have no idea where this file is. It cannot be found anywhere on the C drive.
Why can’t the path to this important configuration file be clearly provided to users?

I look at the document and try to find opencode.json for two days, until found this issue.
That is really confused, and in my mind, I hear "What the f**k is that!"

I want to provide a insight into my journey towards having the opencode.json saved finally at the correct location:

When trying to find out, how to add a specific LMStudio adress, I got caught up in looking for the opencode.json inside ~/.config/opencode/

That looked like a normal node project directory to me, so I thought that should definitely not be it and there was no default opencode.json or opencode.example.json so I looked elsewhere.

I somehow found out that there is ~/.local/share/opencode/ and ~/.local/state/opencode/

In each I put the opencode.json and that did not work. Then after further research I stumbled on this thread and finally found out: I have to create the opencode.json inside the directory myself. That directory that I assumed was wrong from the start: ~/.config/opencode/

I hope this might provide further information on how the process on the discovery of opencode.json might unfold.

Perhaps it would be good for user experience to add "Open config file (opencode.json)" action somewhere in the TUI/GUI apps that would create the file if it does not exist, then open it in the default editor?

Is opencode.json just for first time launching opencode? the initial settings import?

What happens if you change settings in the TUI? does it sync back to the opencode.json? Or is the opencode.json now out-of-sync with the real state of the TUI? Very confusing

I agree the documentation needs work.

I also can't find a way via the documentation to set Build mode to use "GPT 5.4 medium" for example.

Plus there doesn't seem to be a way via the TUI to set Build to "5.4 medium" and Plan to "5.4 high".

I have not managed to achieve it manually by following the documentation, or by asking AI. Maybe I'm just stupid but I really think the documentation lacking, plus the behaviour of opencode.json is confusing.

It is my expectation if you have a settings file, and you change a setting in the app, the change is written to the settings file

Navigation Menu

Repository navigation

No opencode.json file #4208

Description

OpenCode version

Steps to reproduce

Screenshot and/or share link

Operating System

Terminal

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

No opencode.json file #4208

Description

Description

OpenCode version

Steps to reproduce

Screenshot and/or share link

Operating System

Terminal

Activity

github-actions commented on Nov 11, 2025

rekram1-node commented on Nov 11, 2025

agarzon commented on Nov 11, 2025

rekram1-node commented on Nov 11, 2025

agarzon commented on Nov 11, 2025

rekram1-node commented on Nov 11, 2025

nirvdrum commented on Jan 11, 2026

carrot-codeing commented on Jan 12, 2026

mello29 commented on Jan 23, 2026

sebthom commented on Feb 1, 2026

pmavrodiev commented on Feb 2, 2026

agarzon commented on Feb 2, 2026

FuzzySlipper commented on Feb 14, 2026

vanyauhalin commented on Feb 24, 2026

super163-lkjg commented on Feb 26, 2026

xpader commented on Mar 16, 2026

Verizane commented on Mar 17, 2026

jgrosic commented on Mar 30, 2026

mejobloggs-cw commented on May 2, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions