Mastering OpenCode Context
Introduction: Why Context Management Matters
Welcome to "Customizing OpenCode for Your Projects"! Imagine trying to find a specific document on a desk that is buried under thousands of old receipts, candy wrappers, and random sticky notes. It would take a long time to find what you need, and you might accidentally grab the wrong piece of paper. This is exactly what happens to OpenCode when it tries to understand a project filled with unnecessary files.
OpenCode relies on Context to give you helpful suggestions. Context is the collection of files and code snippets that the AI currently "sees" and analyzes. If your project is cluttered with thousands of auto-generated files, system logs, or heavy library code, OpenCode's Context becomes noisy. This noise can lead to slower responses, irrelevant suggestions, or the AI missing the important files entirely because its memory is full of junk.
In this lesson, we will learn how to take control of this Context. We will teach OpenCode exactly what to focus on and what to ignore, ensuring that your coding sessions are fast, efficient, and relevant to the task at hand.
Checking What OpenCode Currently Sees
Before we start decluttering, let's understand what OpenCode is currently looking at by asking a simple question in the chat interface.
Command:
Output (illustrative example):
In the example output above, notice that the actual code you wrote (main.py, analysis.py, tests/) is a tiny fraction of what OpenCode is seeing. The venv folder alone contains over 1,200 files. This is a perfect example of a project where auto-generated files can flood OpenCode's change tracking with irrelevant events.
Configuring Ignore Patterns in opencode.json
To filter out file change noise, add a watcher.ignore field to your project's opencode.json configuration file. OpenCode runs a file watcher in the background — a process that listens for file changes on disk so it can track what was modified during your session. In a typical Python project, every time your code runs, Python regenerates __pycache__/*.pyc files. Without ignore rules, each of those writes triggers a watcher event, flooding OpenCode's change tracking with hundreds of irrelevant entries.
Create opencode.json in your project's root directory and add the following:
Each entry in the ignore array is a glob pattern. OpenCode reads this configuration at startup and suppresses file change notifications for any matching paths. This keeps the file change tracker clean and focused on edits you actually made — not on cache files Python regenerated automatically.
Important distinction: watcher.ignore is about change tracking, not access control. Files inside ignored directories remain fully accessible — OpenCode can still read or list them if you ask. The watcher simply stops listening for modifications in those folders, keeping your change-tracking feed clean and free of noise.
Choosing What to Exclude
Deciding what to put in your watcher.ignore array is a strategic choice. We generally categorize files into two groups: those that are Always Safe to Exclude and those that we Exclude by Default but might need later.
First, let's look at files that are always safe to exclude. These are usually system files, editor settings, or cache files that are regenerated automatically. They contain no logic relevant to your coding tasks.
Always Exclude:
Next, we have files that we exclude by default to keep change tracking clean, even though they contain code. This usually includes heavy folders like venv (for Python). While these contain code, you do not want change events from thousands of library files flooding your session every time Python touches them automatically.
Exclude by Default:
By adding these patterns to the watcher.ignore array in your opencode.json, you drastically reduce the noise. You are telling OpenCode, "Ignore the machinery; look at my blueprint."
Verifying Your Exclusions Work
After saving your ignore patterns, it is important to verify that OpenCode's file watcher has registered the new rules. Because watcher.ignore affects change tracking — not file listing — the most reliable way to confirm your configuration is working is to observe watcher behavior directly.
The principle is straightforward: edits inside ignored directories should not appear in OpenCode's changed-files reporting, while edits to your source files should.
Try this two-step check:
-
Modify a file inside an ignored path — for example, touch or edit any file under
venv/— then askOpenCodewhich files have recently changed. It should not report that file. -
Edit one of your own source files, such as
main.py, and repeat the check. That change should be reported.
Illustrative example — what you might observe after step 2:
If changes from ignored directories are still appearing in the list, double-check that your opencode.json is saved in the project root and that OpenCode was restarted after the configuration change.
Temporarily Including Ignored Files
There is a very important distinction to make here: ignored does not mean inaccessible. The watcher.ignore configuration sets a default focus for change tracking — it is not a permanent barrier to accessing files. There will be times when you actually do need to examine a file inside an ignored folder, such as when you are debugging a library error or checking a specific log entry.
OpenCode allows you to explicitly reference any file by using the @ symbol followed by the file path. This directs OpenCode to read that specific file on demand, regardless of whether its directory appears in the watched paths.
Command:
Output (illustrative example):
This feature gives you the best of both worlds. You get a clean change-tracking feed 99% of the time, but you retain the ability to dive deep into dependencies or logs the moment you need to. You do not need to modify your opencode.json to access these files; you just need to point to them directly.
Summary and Preparing for Practice
In this lesson, we established the foundation for a clean and efficient OpenCode environment. We learned that Context Management is crucial for preventing the AI from getting distracted by irrelevant file-change noise. We practiced configuring watcher.ignore in opencode.json to suppress watcher events from system junk, large libraries, and logs. Finally, we learned that files in ignored directories remain fully accessible and can be brought into any conversation using an explicit @filepath reference.
Key Takeaways:
- Watcher noise is the enemy: Don't let auto-generated files flood your change-tracking feed.
- Ignore is not Delete: Ignoring files removes them from change tracking; it does not block
OpenCodefrom reading or listing them. - Focus first: Exclude heavy folders by default to keep change tracking clean and your session focused on edits that matter.
- Override when needed: Use
@filepathto bring any file into the conversation on demand.
Now that you understand the theory and the commands, you are ready to practice setting up these configurations yourself. In the upcoming exercises, you will create your own ignore configuration and observe firsthand how it changes OpenCode's file watcher behavior.
