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. While OpenCode works well on Windows out of the box, a couple of friction points tripped me up early on.

This guide focuses specifically on OpenCode 2 (the version using the @opencode/cli package).

Whether it’s in-app updates failing after installation, a background process staying alive when you want your PC back for gaming, or default compaction settings discarding too much history when running 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

While that works for the initial setup, it creates 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 are forced to jump back to an external terminal to run a manual install.

Instead of passing the flag to an individual npm install command, you can permit scripts for the package in your user configuration:

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

This writes the setting directly to your user-level .npmrc file (%USERPROFILE%\.npmrc). It saves the permission for future npm updates, so /update can run the necessary installation scripts automatically.

To verify the setting:

npm config get allow-scripts

You should see:

@opencode/cli

Keep in mind that other update failures can still happen (such as network hiccups or registry issues), and if you have explicitly configured ignore-scripts = true in npm, that setting will override 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 you use your machine solely as a dedicated coding workstation, having that shared background process running continuously might not bother you. But if your Windows PC is also your gaming rig or everyday workstation, you might prefer not having an AI agent service idling in the background. When I close my terminal, I want to minimise background activity 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 dedicated server instance, and when you exit your terminal, that instance shuts down.

Bear in mind that disabling OpenCode’s background service only manages 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 will remain loaded in memory until you close it.

How to undo it

#

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

opencode service unset disabled

Tune context compaction for local models

#

OpenCode supports both .json and .jsonc configuration files. Using .jsonc is particularly convenient 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 you can use Notepad or any text editor you prefer. If you already have an existing configuration, make a quick backup before editing and merge the changes below into it.)

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

A couple of 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). Keeping that percentage-based trigger is ideal because it automatically adapts if you switch between models with different context sizes.

However, the default number of recent tokens it preserves unsummarised (keep.tokens) is conservative, defaulting to roughly 15,000 tokens. 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.

You can tune this by specifying 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 it gives your agent a much deeper immediate memory of recent code changes and tool outputs.

There is a trade-off to consider: keeping more tokens means less remaining space in the context window for new work before the next compaction triggers, and processing larger context buffers can increase response latency and memory use on your local model runner. Choose a keep.tokens value that fits the context size you have actually configured for 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. Prevent the shared background service from running idle
opencode service set disabled true

# 3. Edit your global 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 are iterating with a large local model or freeing up your machine for an evening of gaming.

Happy coding!