Suggested OpenCode settings for Windows

Running AI coding tools natively on Windows can sometimes feel like playing on hard mode compared to Linux or macOS. OpenCode works well on Windows out of the box, but a couple of friction points tripped me up early on.

This guide covers OpenCode 2 (the version using the @opencode/cli package).

In-app updates failing after installation, a background process staying alive when you want your PC back for gaming 🎮, default compaction settings discarding too much history with modern local models: a few quick configuration tweaks sort them all out.

Handle npm script permissions for OpenCode updates

#

If npm blocks OpenCode’s installation script, you’ll run into issues when updating.

OpenCode relies on lifecycle scripts: pieces of code that a package runs automatically during installation (for example, to download the pre-compiled binary matching your operating system and architecture). Depending on your version of npm and your global configuration, npm may restrict these scripts by default.

The common workaround you see online is to pass an inline flag during manual installation:

npm install -g --allow-scripts=@opencode/cli @opencode/cli

That works for the initial setup, but it sets a subtle trap. OpenCode 2 has a built-in /update command to update itself from inside the terminal interface. When you run /update, OpenCode triggers an npm update in the background without that extra command-line flag. If npm restricts lifecycle scripts, the update fails, and you have to jump back to an external terminal to run a manual install. 🤦‍♂️

Instead of passing the flag to a single npm install command, permit scripts for the package in your user configuration:

npm config set allow-scripts=@opencode/cli --location=user

This writes the setting to your user-level .npmrc file (%USERPROFILE%\.npmrc), so future npm updates (including the ones /update triggers) can run the installation scripts automatically.

To verify the setting:

npm config get allow-scripts

You should see:

@opencode/cli

✅ That’s it. Other update failures can still happen (such as network hiccups or registry issues), and if you have explicitly set ignore-scripts = true in npm, that setting overrides this permission.

Stop the background service when you are done

#

By default, OpenCode 2 starts a shared background service to coordinate sessions and server instances across terminal windows.

If your machine is a dedicated coding workstation, that process running continuously might not bother you. But if your Windows PC is also your gaming rig, you might prefer not to have an AI agent service idling in the background. When I close my terminal, I want as little running as possible so my CPU and GPU are ready for gaming or other heavy workloads.

You can disable the shared background service with a single command:

opencode service set disabled true

Once disabled, OpenCode runs in standalone mode. Each CLI session starts its own server instance, and when you exit your terminal, that instance shuts down.

Bear in mind this only covers OpenCode itself. If you run local models via an external runner (such as llama.cpp, Ollama, or LM Studio), that model server is a separate process and stays loaded in memory until you close it.

How to undo it

#

If you need the shared background service again (for instance, for client pairing across devices), you can revert to the default behaviour at any time:

opencode service unset disabled

Tune context compaction for local models

#

If you run local models (like I explored when testing local coding models on a gaming rig), one setting worth tuning is compaction.

Two basic concepts explain why:

• Tokens: the chunks of text (roughly words or parts of words) that language models use to process text.
• Context window: the maximum number of tokens a model can handle in a single request, including both input and response.

OpenCode uses automatic compaction: when a conversation approaches the limit of the model’s context window, it summarises earlier dialogue and preserves recent messages.

By default, OpenCode triggers compaction at a sensible threshold (roughly 10% before reaching the context limit). I’d keep that percentage-based trigger, because it adapts automatically if you switch between models with different context sizes.

The number of recent tokens it keeps unsummarised (keep.tokens) is more conservative: roughly 15,000 tokens by default. With a large context window (such as a local qwen3.8-27b model running with 192k or 256k tokens), you may prefer to keep more recent conversation in full rather than relying on the summary.

Edit your OpenCode configuration

#

OpenCode supports both .json and .jsonc configuration files. I prefer .jsonc because it lets you add comments to your configuration. On Windows, OpenCode looks for your user-level configuration under your profile directory:

code $HOME\.config\opencode\opencode.jsonc

(Running code opens the file in Visual Studio Code, but Notepad or any other text editor works too. If you already have a configuration, make a quick backup before editing and merge the changes below into it.)

Set a larger retention value, such as 64k tokens (65536):

{
  "$schema": "https://opencode.ai/config.json",
  "compaction": {
    "auto": true,
    "keep": { "tokens": 65536 }
  }
}

With this setting, OpenCode aims to keep roughly 65,000 tokens of recent conversation alongside the generated summary. The retained amount is approximate, but your agent remembers far more of its recent code changes and tool outputs in full.

There is a trade-off: keeping more tokens leaves less space in the context window for new work before the next compaction triggers, and larger contexts can increase response latency and memory use on your local model runner. Pick a keep.tokens value that fits the context size you have actually configured on your local server.

Quick cheat sheet

#

Here is a quick summary of the settings:

# 1. Allow in-app /update to run installation scripts
npm config set allow-scripts=@opencode/cli --location=user

# 2. Stop the shared background service from idling
opencode service set disabled true
#    (undo with: opencode service unset disabled)

# 3. Edit your user config to tune compaction for local models
code $HOME\.config\opencode\opencode.jsonc

A couple of CLI commands and a tuned opencode.jsonc file make OpenCode 2 behave much more cleanly on Windows, whether you’re iterating with a large local model or freeing up your machine for an evening of gaming.

Happy coding!