Configuring OpenCode Behavior

Welcome to the third lesson in our Foundation course. In the previous sessions, you learned how to install OpenCode and manage the daily workflow of creating files, running commands, and handling session history. You have moved from setting up the tool to actively using it for basic coding tasks. However, as your projects become more complex, sticking to the default settings may no longer be efficient.

In this lesson, we focus on customizing how the agent operates to suit your specific needs. We will explore how to monitor your token usage and costs, how to switch between different AI models depending on the difficulty of your task, and how to change the agent's role from a builder to a planner. Finally, we will look at configuring security permissions to control exactly what the agent is allowed to do on your computer.

When you use an AI agent, every message you send and every response you receive consumes tokens. These tokens are the basic units of data that AI models process, and they often translate directly to real-world costs or quota limits. Tracking these metrics is essential for budgeting and understanding how efficiently you work.

Understanding tokens is fundamental to working with AI systems. A token is not exactly a word—it is a chunk of text that the model processes as a single unit. On average, one token equals roughly four characters in English, meaning a 100-word paragraph might consume around 130-150 tokens. This matters because API providers charge based on token consumption, and different operations have different costs. Input tokens (what you send to the model, including file contents) are typically cheaper than output tokens (what the model generates back). Additionally, modern AI systems use caching to reduce costs: if you send similar context repeatedly, the system can reuse previously processed data rather than recomputing everything from scratch.

OpenCode provides a built-in command to view this data directly from your terminal. You run this command from your standard command line, not from inside the interactive OpenCode session:

opencode stats

Example Output:

┌────────────────────────────────────────────────────────┐
│                       OVERVIEW                         │
├────────────────────────────────────────────────────────┤
│Sessions                                              3 │
│Messages                                             12 │
│Days                                                  1 │
└────────────────────────────────────────────────────────┘
┌────────────────────────────────────────────────────────┐
│                    COST & TOKENS                       │
├────────────────────────────────────────────────────────┤
│Total Cost                                        $0.23 │
│Avg Cost/Day                                      $0.23 │
│Avg Tokens/Session                                 6453 │
│Input                                             15240 │
│Output                                             4120 │
│Cache Read                                         8500 │
│Cache Write                                        2100 │
└────────────────────────────────────────────────────────┘

The output is divided into two main sections. The Overview shows your activity volume: the number of sessions you have started and total messages exchanged. The Cost & Tokens section breaks down the financial impact and data usage, including the split between Input tokens (what you typed and the files the AI read) and Output tokens (the code and text the AI generated). The Cache Read and Cache Write metrics show how much data was reused versus newly processed—higher cache read values indicate more efficient sessions. Monitoring this data helps you decide whether you need to be more concise or if you can afford to use more powerful models.