OpenAgentsControl/dev/ai-tools/opencode/context/CONTEXT-DEEP-DIVE.md

OpenCode Context Deep Dive: Complete Guide

Last verified: Dec 7, 2025
Source code verified: packages/opencode/src/session/system.ts, prompt.ts, transform.ts

---

🎯 Context in 60 Seconds

Every time you send a message to OpenCode, it builds a context (like a brief for the AI). Think of it like preparing a sandwich:

🍞 Header         → "You are Claude" (if using Anthropic)            ~12 tokens
🥬 Base Prompt    → Big instructions (1,300-3,900 words)              ~2,000 tokens
🧀 Environment    → "You're in /Users/you/project, 50 files..."      ~200 tokens
🥓 Your Rules     → AGENTS.md, CLAUDE.md (your custom instructions)  ~500 tokens
🍖 Tools          → "You can read, write, edit..." (16 tools)         ~6,600 tokens
🍞 Your Message   → "Fix the bug in auth.ts"                          ~10 tokens
                                                           ─────────────────────────
                                                           Total: ~9,322 tokens

💰 The Cost Story

Without Caching (Ollama, most models):

• Every request: 9,322 tokens × full price
• Or FREE (local models like Ollama)
• 🚨 Problem: Uses 50-100% of small context windows!

With Caching (Claude/Anthropic only):

• First request: 9,322 tokens × full price = $0.028
• Next requests: 9,000 cached (10% price) + 322 new = $0.004
• Savings: 85% cheaper! Cache lasts 5 minutes
• Static parts (base prompt, tools) reused automatically

The TUI shows total tokens INCLUDING cached reads, so high numbers are actually GOOD for Claude!

---

🔄 How Caching Actually Works

What Gets Cached?

OpenCode caches specific messages automatically:

// From: packages/opencode/src/provider/transform.ts:23-63

const system = msgs.filter((msg) => msg.role === "system").slice(0, 2)
const final = msgs.filter((msg) => msg.role !== "system").slice(-2)

Translation: OpenCode marks these messages as cacheable:

1. First 2 system messages (base prompt, environment+tools)
2. Last 2 conversation messages (your previous question + AI's answer)

Visual example:

Request 1: "Fix auth bug"
├─ [System 1] Header + Base Prompt          [CACHEABLE ✅]
├─ [System 2] Environment + Custom + Tools  [CACHEABLE ✅]
├─ [User] "Fix auth bug"                    [NOT CACHED]
└─ [Assistant] "Here's the fix..."          [NOT CACHED]

Request 2: "Add tests"  
├─ [System 1] Header + Base Prompt          [CACHE HIT! 💰]
├─ [System 2] Environment + Custom + Tools  [CACHE HIT! 💰]
├─ [User] "Fix auth bug"                    [CACHEABLE ✅]
├─ [Assistant] "Here's the fix..."          [CACHEABLE ✅]
├─ [User] "Add tests"                       [NOT CACHED]
└─ [Assistant] "Here are the tests..."      [NOT CACHED]

Request 3: "Explain the tests"
├─ [System 1] Header + Base Prompt          [CACHE HIT! 💰]
├─ [System 2] Environment + Custom + Tools  [CACHE HIT! 💰]
├─ ... (earlier messages truncated)
├─ [User] "Add tests"                       [CACHE HIT! 💰]
├─ [Assistant] "Here are the tests..."      [CACHE HIT! 💰]
├─ [User] "Explain the tests"               [NOT CACHED]
└─ [Assistant] "The tests work by..."       [NOT CACHED]

How It's Stored

Caching happens on the provider's servers (not locally):

1. Anthropic receives your request with special markers:

   {
    "messages": [
      {
        "role": "system",
        "content": "You are Claude...",
        "cache_control": { "type": "ephemeral" }  // ← Cache marker
      }
    ]
   }
   

2. Anthropic computes a hash of the message content

   • Same content = Same hash = Cache hit!
   • One character change = Different hash = Cache miss

3. Cache is stored on Anthropic's servers for your API key

   • Keyed by: message content hash + your API key
   • Not shared between users
   • Not stored locally

4. OpenCode tracks cache status in message metadata:

   {
    "tokens": {
      "input": 1200,
      "cache": {
        "read": 8500,    // ← Anthropic says "I already have this"
        "write": 0       // ← New content added to cache
      }
    }
   }
   

Cache Expiration & Refresh

Lifespan: 5 minutes of inactivity

0:00 - Request 1: Cache written (full price)
0:30 - Request 2: Cache hit! (10% price)
1:00 - Request 3: Cache hit! (10% price)
4:50 - Request 4: Cache hit! (10% price)
... (silence for 5 minutes)
10:00 - Request 5: Cache expired, rebuilt (full price)
10:30 - Request 6: Cache hit again! (10% price)

Auto-refresh: Every cache hit resets the 5-minute timer

Which Providers Support Caching?

Source: packages/opencode/src/provider/transform.ts:65-74

export function message(msgs: ModelMessage[], providerID: string, modelID: string) {
  if (providerID === "anthropic" || modelID.includes("anthropic") || modelID.includes("claude")) {
    msgs = applyCaching(msgs, providerID)
  }
  return msgs
}

Verified Provider Support:

Provider	Models	Caching Support	Cache Format	Notes
Anthropic	Claude 3.5 Sonnet Claude 3.5 Haiku Claude 3 Opus/Sonnet	✅ Yes	cacheControl: { type: "ephemeral" }	Native support, best implementation
OpenRouter	When routing to Claude	✅ Yes	cache_control: { type: "ephemeral" }	Only if backend is Anthropic
AWS Bedrock	Claude on Bedrock	✅ Yes	cachePoint: { type: "ephemeral" }	AWS-specific format
OpenAI	GPT-4, GPT-4 Turbo o1, o3, GPT-5	⚠️ Different	promptCacheKey: sessionID	Different system, not as effective
OpenCode API	Big Pickle	✅ Yes	Routes through Anthropic	Backend uses Anthropic, so caching works
Ollama	All local models	❌ No	N/A	Local models don't support caching
LM Studio	All local models	❌ No	N/A	Local server, no cloud cache
Together AI	Qwen, Llama, etc.	❌ No	N/A	No caching support
Google AI	Gemini 1.5, 2.0	❌ No	N/A	Not supported by provider
Azure OpenAI	GPT-4 on Azure	⚠️ Varies	Depends on Azure config	Check your Azure setup

How to Tell if Caching is Working

Method 1: Check Token Breakdown

# View your session tokens
cat ~/.local/share/opencode/storage/message/ses_YOUR_ID/*.json | jq '.tokens'

# If you see this, caching is working:
{
  "cache": {
    "read": 8500  // ← Non-zero = cache hit!
  }
}

# If you see this, no caching:
{
  "cache": {
    "read": 0     // ← Zero = no cache support
  }
}

Method 2: TUI Display

Context
9,842 tokens   ← If this stays HIGH but cost stays LOW = caching works!

Method 3: Cost Pattern

Request 1: $0.028  (first request)
Request 2: $0.004  (85% cheaper)
Request 3: $0.004  (still cheap)

If costs drop dramatically after first request = caching works!

Why Some Models Show Cache But Shouldn't

Big Pickle Mystery Solved:

Your Setup:
├─ You select: "Big Pickle" (Ollama model)
├─ OpenCode CLI sends to: OpenCode API
└─ OpenCode API routes to: Anthropic Claude API
                            ↑
                      Cache happens here!

That's why you see:

• cache.read: 8500 tokens (from Anthropic)
• Costs are charged (not free like local Ollama)
• Same caching behavior as Claude

It's not really Ollama - it's Claude with a different name!

Cache Optimization Tips

For Anthropic/Claude:

1. ✅ Keep long system prompts (they get cached)
2. ✅ Enable all tools you might need (cached after first use)
3. ✅ Long conversations benefit more (2+ messages)
4. ✅ Work in bursts under 5 minutes (cache stays warm)
5. ❌ Don't optimize context size (caching makes it cheap)

For Non-Caching Models:

1. ✅ Minimize system prompts aggressively
2. ✅ Disable unused tools
3. ✅ Remove custom instructions
4. ✅ Use agent prompt overrides
5. ❌ Don't rely on "cheaper subsequent requests"

Technical: Cache Control Application

Source: packages/opencode/src/provider/transform.ts:23-63

function applyCaching(msgs: ModelMessage[], providerID: string): ModelMessage[] {
  const system = msgs.filter((msg) => msg.role === "system").slice(0, 2)
  const final = msgs.filter((msg) => msg.role !== "system").slice(-2)

  const providerOptions = {
    anthropic: { cacheControl: { type: "ephemeral" } },
    openrouter: { cache_control: { type: "ephemeral" } },
    bedrock: { cachePoint: { type: "ephemeral" } },
    openaiCompatible: { cache_control: { type: "ephemeral" } },
  }

  // Apply cache markers to eligible messages
  for (const msg of unique([...system, ...final])) {
    msg.providerOptions = {
      ...msg.providerOptions,
      ...providerOptions[providerID]
    }
  }
  
  return msgs
}

What this does:

1. Finds first 2 system messages
2. Finds last 2 conversation messages
   
3. Adds provider-specific cache markers
4. Provider sees markers and caches those messages

---

📊 Visual Flow: How Context is Built

graph TD
    A[You type message] --> B{OpenCode starts building context}
    
    B --> C[1️⃣ Add Header]
    C --> C1[Anthropic: 'You are Claude'<br/>Others: Nothing]
    
    B --> D[2️⃣ Add Base Prompt]
    D --> D1{Which model?}
    D1 -->|Claude| D2[anthropic.txt<br/>1,335 words]
    D1 -->|GPT-4| D3[beast.txt<br/>1,904 words]
    D1 -->|GPT-5| D4[codex.txt<br/>3,940 words]
    D1 -->|Gemini| D5[gemini.txt<br/>2,235 words]
    D1 -->|Others/Ollama/Big Pickle| D6[qwen.txt<br/>1,596 words]
    
    B --> E[3️⃣ Add Environment]
    E --> E1[Working directory<br/>Project tree<br/>Date & platform]
    
    B --> F[4️⃣ Search for Custom Instructions]
    F --> F1{Find local files?}
    F1 -->|Yes| F2[Load AGENTS.md<br/>or CLAUDE.md]
    F1 -->|No| F3[Check global<br/>~/.claude/CLAUDE.md]
    
    B --> G[5️⃣ Add Tool Definitions]
    G --> G1{Which tools enabled?}
    G1 -->|Agent config| G2[Load descriptions<br/>for enabled tools]
    G1 -->|All by default| G3[Load all 16 tools<br/>~6,600 tokens!]
    
    C1 & D2 & D3 & D4 & D5 & D6 & E1 & F2 & F3 & G2 & G3 --> H[6️⃣ Combine Everything]
    
    H --> I[7️⃣ Apply Caching]
    I --> I1{Anthropic/Claude?}
    I1 -->|Yes| I2[Mark first 2 system<br/>messages as cacheable]
    I1 -->|No| I3[No caching]
    
    I2 & I3 --> J[8️⃣ Add Your Message]
    
    J --> K[Send to AI Model]
    
    K --> L{First request?}
    L -->|Yes| M[Full cost:<br/>All tokens charged]
    L -->|No + Cached| N[Discounted:<br/>90% cached at 10% cost]
    
    M & N --> O[AI Responds]
    
    style A fill:#e1f5ff
    style K fill:#fff4e1
    style M fill:#ffe1e1
    style N fill:#e1ffe1
    style O fill:#f0e1ff

---

🏗️ The Layer Cake Metaphor

Think of OpenCode context like building a layer cake for the AI to "eat":

Layer 1: The Foundation (Header)

• What: A tiny label saying who the AI is
• Size: 0-12 tokens
• Example: "You are Claude, made by Anthropic"
• Why: Some models need this identity reminder

Layer 2: The Recipe Book (Base Prompt)

• What: Detailed instructions on how to behave
• Size: 1,300-3,900 words (1,700-5,100 tokens!)
• Example: "Be concise. Use tools. Don't write malicious code..."
• Why: Different models need different instruction styles
• 🚨 Problem: This layer is HUGE and different per model!

Layer 3: The Kitchen Tour (Environment)

• What: Info about the project you're working in
• Size: 40-600 tokens
• Example: "You're in /project, here's the file tree with 50 files..."
• Why: AI needs to know what files exist and where it is

Layer 4: The House Rules (Custom Instructions)

• What: YOUR personal preferences and rules
• Size: 0-5,000 tokens (highly variable)
• Files: AGENTS.md, CLAUDE.md, or files in config.instructions
• Example: "Always use TypeScript. Follow our style guide..."
• Why: Customize AI behavior for your team/workflow

Layer 5: The Toolbox Manual (Tool Definitions)

• What: Descriptions of what tools the AI can use
• Size: 0-6,600 tokens (330-1,900 per tool)
• Example: "read: Read file contents. write: Create new files..."
• Why: AI needs to know what actions it can take
• 🚨 Problem: All 16 tools = 6,600 tokens by default!

Layer 6: Your Request (The Actual Question)

• What: What you just typed
• Size: ~1.3 tokens per word
• Example: "Fix the authentication bug in auth.ts"
• Why: This is what you want help with!

---

💡 The Key Insight: Most Context is STATIC

┌─────────────────────────────────────────┐
│ STATIC CONTENT (Same Every Request)     │ 8,000-10,000 tokens
├─────────────────────────────────────────┤
│ • Base Prompt      → 2,000 tokens       │ ← Huge!
│ • Tool Definitions → 6,600 tokens       │ ← Wasteful if unused!
│ • Environment      →   200 tokens       │
│ • Custom Rules     →   500 tokens       │
└─────────────────────────────────────────┘
         ↓ This repeats EVERY request
         
┌─────────────────────────────────────────┐
│ DYNAMIC CONTENT (Changes Each Request)  │ 10-100 tokens
├─────────────────────────────────────────┤
│ • Your Message     →    15 tokens       │
└─────────────────────────────────────────┘

Without caching: You pay for all 8,000+ tokens every time!
With caching (Anthropic): You pay full price once, then 10% for the static parts!

---

🎭 Different Models = Different Base Layers

Here's why you see different token counts for different models:

Model	Base Prompt	Size	Why Different?
Claude	anthropic.txt	1,736 tokens	Optimized for Claude's style
GPT-4	beast.txt	2,475 tokens	Detailed reasoning instructions
GPT-5	codex.txt	5,122 tokens	Advanced multi-step guidance
Gemini	gemini.txt	2,906 tokens	Google-specific format
Ollama/Big Pickle	qwen.txt	2,075 tokens	Open-source model format

🚨 Key Point: Your Ollama model gets the same 2,075-token prompt as GPT-4, even though it has a tiny 8k context window!

---

🔄 How Caching Saves You Money

First Request (No Cache):

Request 1: "Hi"
├─ Base Prompt:        2,000 tokens × $3.00/1M  = $0.0060
├─ Tools:              6,600 tokens × $3.00/1M  = $0.0198
├─ Environment:          200 tokens × $3.00/1M  = $0.0006
├─ Your Message:          10 tokens × $3.00/1M  = $0.0000
└─ AI Response:          100 tokens × $15.00/1M = $0.0015
                                    Total: $0.0279

Second Request (With Cache):

Request 2: "Thanks"
├─ Base Prompt:        2,000 tokens × $0.30/1M  = $0.0006 (cached!)
├─ Tools:              6,600 tokens × $0.30/1M  = $0.0020 (cached!)
├─ Environment:          200 tokens × $0.30/1M  = $0.0001 (cached!)
├─ Your Message:          10 tokens × $3.00/1M  = $0.0000
└─ AI Response:          100 tokens × $15.00/1M = $0.0015
                                    Total: $0.0042
                                    
Savings: 85% cheaper!

🎁 Cache expires after 5 minutes of inactivity, then rebuilds automatically.

---

🎯 The Problem (And Solutions)

Problem 1: Local Models (Ollama) Waste Context

Ollama Model: 8,000 token context limit
├─ Base Prompt:        2,075 tokens (26%!) 😱
├─ Tools:              6,600 tokens (82%!) 😱😱
└─ Remaining for you:  -675 tokens ❌ DOESN'T FIT!

Solution: Minimize everything (see optimization section below)

Problem 2: You Don't Control Base Prompts

You can't easily change the 2,000+ token base prompt without editing source code.

Solution: Override with agent prompt: field (explained below)

Problem 3: Tools Load By Default

All 16 tools = 6,600 tokens, even if you only need 3.

Solution: Explicitly disable unused tools (explained below)

---

🚀 Quick Wins

Before diving into the technical details, here are the fastest ways to reduce context:

For Claude/Anthropic (Use Full Context)

# Don't optimize - caching makes it cheap!
# Keep all tools and instructions

For Ollama (Minimize Everything)

# .opencode/agent/ollama.md
---
description: "Ollama optimized"
prompt: "Code assistant"  # ← Replaces 2,075 token base prompt!
tools:
  read: true
  write: true
  edit: true
  # All others automatically false = Saves 5,900 tokens!
---

# Remove custom instructions
mv ~/.claude/CLAUDE.md ~/.claude/CLAUDE.md.disabled  # Saves 200-2,000 tokens

# Result: 750 tokens instead of 8,000+ (91% reduction!)

---

---

🔍 How to Verify Context for Your Setup

Before diving into details, here's how to check what context YOUR agents are using:

Method 1: Count Agent Tokens (Script)

# Run the token counting script
cd /Users/darrenhinde/Documents/GitHub/opencode
./script/count-agent-tokens.sh AGENT_NAME MODEL_ID PROVIDER

# Examples:
./script/count-agent-tokens.sh build claude-sonnet-4 anthropic
./script/count-agent-tokens.sh ollama qwen2.5:latest ollama
./script/count-agent-tokens.sh your-custom-agent big-pickle opencode

# Output shows:
# - Base prompt tokens
# - Environment tokens
# - Custom instruction files found
# - Tool tokens
# - Total estimated tokens

Method 2: Check TUI During Session

When you run OpenCode in TUI mode:

opencode  # Start TUI

# Top right shows:
Context
9,842 tokens   ← Total tokens (includes cached!)
12% used       ← % of context window
$0.00 spent    ← Cost so far

🎯 Key Insight: The token count includes cache.read tokens, so:

• High number + Claude = GOOD (90% of it is cached/cheap)
• High number + Ollama = BAD (eating your limited context)

Method 3: Inspect Session Data (Advanced)

# Find your session ID in TUI (top of screen: "Session: ses_...")
SESSION_ID="ses_YOUR_SESSION_ID_HERE"

# View token breakdown
cat ~/.local/share/opencode/storage/message/$SESSION_ID/*.json | \
  jq '.tokens'

# Example output:
{
  "input": 1200,        ← New tokens this request
  "output": 150,        ← AI response tokens
  "reasoning": 0,       ← Reasoning tokens (o1/o3 only)
  "cache": {
    "read": 8500,       ← Reused from cache (cheap!)
    "write": 0          ← New cache writes
  }
}

# Calculate real cost:
# Cached: 8500 × $0.30/1M = $0.0026
# Input:  1200 × $3.00/1M = $0.0036
# Output:  150 × $15.00/1M = $0.0023
# Total: $0.0085 (not $0.0285 without cache!)

Method 4: Check What Files Are Loaded

# Find custom instruction files being loaded
cd your-project
find . -name "AGENTS.md" -o -name "CLAUDE.md" -o -name "CONTEXT.md" 2>/dev/null

# Check global files
ls -la ~/.config/opencode/AGENTS.md 2>/dev/null
ls -la ~/.claude/CLAUDE.md 2>/dev/null

# Count words in custom files
wc -w .opencode/AGENTS.md ~/.claude/CLAUDE.md

# Estimate tokens (words × 1.3)

Method 5: List Enabled Tools

# Check your opencode.json
cat opencode.json | jq '.tools'

# Or check agent config
cat .opencode/agent/your-agent.md | grep -A 20 "tools:"

# Count enabled tools:
# Each tool ≈ 200-1,800 tokens
# All 16 tools ≈ 6,600 tokens total

Quick Diagnostic Table

Symptom	Likely Cause	Fix
8,000+ tokens on "Hi"	Base prompt + all tools loaded	Use minimal agent, disable tools
Same tokens every request	No caching OR local model	Switch to Claude for caching
9k cache + 1k input	Perfect! Caching working	Nothing, this is optimal!
Context 90% used (Ollama)	Too much context for small window	Minimize base prompt, disable tools
Can't fit full context	Project too large + tools + prompt	Reduce tool count, use agent override

Example Verification Session

# 1. Create minimal agent
cat > .opencode/agent/test.md << 'EOF'
---
description: "Test minimal context"
prompt: "Code assistant"
tools:
  read: true
---
EOF

# 2. Count tokens
./script/count-agent-tokens.sh test qwen2.5:latest ollama

# 3. Compare before/after
# Before: ~8,000 tokens
# After: ~400 tokens
# Savings: 95%!

# 4. Test in TUI
opencode --agent test
# Type: "hi"
# Check Context in top right

---

Now let's dive into the technical details...

---

Table of Contents

1. How Context is Built (Step-by-Step)
2. Model-Specific Prompts
3. How Caching Works
4. Custom Instruction Files
5. Tool Loading
6. Optimization Strategies
7. Complete Token Breakdown Examples

---

How Context is Built

Every request to the AI follows this exact sequence. Here's the verified code flow:

Step 1: System Prompt Assembly

Source: packages/opencode/src/session/prompt.ts:492-512

async function resolveSystemPrompt(input: {
  system?: string
  agent: Agent.Info
  providerID: string
  modelID: string
}) {
  let system = SystemPrompt.header(input.providerID)          // Step 1
  system.push(...(() => {                                     // Step 2
    if (input.system) return [input.system]
    if (input.agent.prompt) return [input.agent.prompt]
    return SystemPrompt.provider(input.modelID)
  })())
  system.push(...(await SystemPrompt.environment()))          // Step 3
  system.push(...(await SystemPrompt.custom()))               // Step 4
  
  // Combine into max 2 messages for caching
  const [first, ...rest] = system
  system = [first, rest.join("\n")]
  return system
}

The 4 Components (In Order)

1️⃣ Header (Provider-Specific)

Source: packages/opencode/src/session/system.ts:20-23

export function header(providerID: string) {
  if (providerID.includes("anthropic")) return [PROMPT_ANTHROPIC_SPOOF.trim()]
  return []
}

What gets added:

• Anthropic only: "You are Claude, a large language model trained by Anthropic." (~9 words)
• All others: Nothing

Token cost:

• Anthropic: ~12 tokens
• Others: 0 tokens

---

2️⃣ Base Model Prompt (Model-Specific)

Source: packages/opencode/src/session/system.ts:25-31

export function provider(modelID: string) {
  if (modelID.includes("gpt-5")) return [PROMPT_CODEX]
  if (modelID.includes("gpt-") || modelID.includes("o1") || modelID.includes("o3")) 
    return [PROMPT_BEAST]
  if (modelID.includes("gemini-")) return [PROMPT_GEMINI]
  if (modelID.includes("claude")) return [PROMPT_ANTHROPIC]
  return [PROMPT_ANTHROPIC_WITHOUT_TODO]  // Default fallback
}

Override Priority:

1. If --system "custom" flag used → Use that
2. If agent has prompt: field → Use agent prompt
3. Otherwise → Select by model ID

Verified Prompt Files & Token Counts:

Model Pattern	File	Words	Approx Tokens	Used By
gpt-5	codex.txt	3,940	~5,122	GPT-5, o1-pro, o1-2024-12-17
gpt-*, o1, o3	beast.txt	1,904	~2,475	GPT-4, o1, o3
gemini-	gemini.txt	2,235	~2,906	Gemini models
claude	anthropic.txt	1,335	~1,736	Claude 3.5, 3, etc.
Default	qwen.txt	1,596	~2,075	Big Pickle, Ollama, DeepSeek, etc.

🔥 Key Insight: Models that don't match specific patterns (like Big Pickle, Ollama models, most local models) get the qwen.txt prompt by default, which is ~2,075 tokens!

---

3️⃣ Environment Context

Source: packages/opencode/src/session/system.ts:33-56

export async function environment() {
  const project = Instance.project
  return [
    [
      `Here is some useful information about the environment you are running in:`,
      `<env>`,
      `  Working directory: ${Instance.directory}`,
      `  Is directory a git repo: ${project.vcs === "git" ? "yes" : "no"}`,
      `  Platform: ${process.platform}`,
      `  Today's date: ${new Date().toDateString()}`,
      `</env>`,
      `<project>`,
      `  ${
        project.vcs === "git"
          ? await Ripgrep.tree({
              cwd: Instance.directory,
              limit: 200,  // ← Max 200 files shown
            })
          : ""
      }`,
      `</project>`,
    ].join("\n"),
  ]
}

What gets added:

1. Working directory path
2. Git repo status
3. Platform (darwin/linux/win32)
4. Today's date
5. Project tree (if git repo):
   • Up to 200 files
   • Shows directory structure
   • ~3-5 tokens per file

Token cost:

• Base info: ~40 tokens
• Project tree: ~3 tokens × number of files (max 200 files = ~600 tokens)
• Typical: 40-400 tokens depending on project size

---

4️⃣ Custom Instructions

Source: packages/opencode/src/session/system.ts:58-115

This is the most misunderstood part! Let me show you exactly what gets loaded:

const LOCAL_RULE_FILES = [
  "AGENTS.md",
  "CLAUDE.md",
  "CONTEXT.md", // deprecated
]

const GLOBAL_RULE_FILES = [
  path.join(Global.Path.config, "AGENTS.md"),        // ~/.config/opencode/AGENTS.md
  path.join(os.homedir(), ".claude", "CLAUDE.md"),   // ~/.claude/CLAUDE.md
]

export async function custom() {
  const config = await Config.get()
  const paths = new Set<string>()

  // 1. Search for LOCAL files (searches UP the directory tree)
  for (const localRuleFile of LOCAL_RULE_FILES) {
    const matches = await Filesystem.findUp(localRuleFile, Instance.directory, Instance.worktree)
    if (matches.length > 0) {
      matches.forEach((path) => paths.add(path))
      break  // ← STOPS after finding first matching file
    }
  }

  // 2. Check GLOBAL files (exact paths only)
  for (const globalRuleFile of GLOBAL_RULE_FILES) {
    if (await Bun.file(globalRuleFile).exists()) {
      paths.add(globalRuleFile)
      break  // ← STOPS after finding first global file
    }
  }

  // 3. Load files from config.instructions (if specified)
  if (config.instructions) {
    for (let instruction of config.instructions) {
      if (instruction.startsWith("~/")) {
        instruction = path.join(os.homedir(), instruction.slice(2))
      }
      let matches: string[] = []
      if (path.isAbsolute(instruction)) {
        matches = await Array.fromAsync(
          new Bun.Glob(path.basename(instruction)).scan({
            cwd: path.dirname(instruction),
            absolute: true,
            onlyFiles: true,
          }),
        ).catch(() => [])
      } else {
        matches = await Filesystem.globUp(instruction, Instance.directory, Instance.worktree)
          .catch(() => [])
      }
      matches.forEach((path) => paths.add(path))
    }
  }

  return Promise.all(Array.from(paths).map(...))
}

Search Behavior (Critical!):

1. Local Files (searches UP from current directory):

   • Looks for: AGENTS.md, CLAUDE.md, CONTEXT.md
   • Searches: Current dir → Parent → Grandparent → ... → Git root
   • Stops: After finding first match (all three files, or just one)
     

2. Global Files (exact paths):

   • ~/.config/opencode/AGENTS.md OR
   • ~/.claude/CLAUDE.md
   • Stops: After finding first one

3. Config Instructions (if you add to opencode.json):

   {
    "instructions": [
      ".opencode/rules.md",
      "~/my-custom-rules.md"
    ]
   }
   

   • Supports globs
   • Loads ALL matches

🚨 Common Misconceptions:

❌ "OpenCode loads ALL .md files in .opencode/"
✅ ONLY loads AGENTS.md, CLAUDE.md, CONTEXT.md (if found)

❌ "OpenCode loads from both local AND global"
✅ Loads ONE local file + ONE global file (or until first match)

❌ "OpenCode always loads custom instructions"
✅ Only if the specific files exist

Token cost:

• Varies widely: 0 - 5,000+ tokens depending on file content
• Typical: 50-500 tokens per file

---

Step 2: Tool Definitions

Source: packages/opencode/src/session/prompt.ts:514-522

async function resolveTools(input: {
  agent: Agent.Info
  sessionID: string
  modelID: string
  providerID: string
  tools?: Record<string, boolean>
  processor: Processor
}) {
  const tools: Record<string, AITool> = {}
  const enabledTools = pipe(
    input.agent.tools,                                  // 1. Agent config
    mergeDeep(await ToolRegistry.enabled(...)),         // 2. Default tools
    mergeDeep(input.tools ?? {}),                       // 3. Request override
  )
  
  // Only load enabled tools
  for (const item of await ToolRegistry.tools(...)) {
    if (Wildcard.all(item.id, enabledTools) === false) continue
    // ... load tool definition
  }
}

Verified Tool Sizes (from source code):

Tool	Words	Tokens	Description Size
todowrite	1,380	~1,794	Largest - complex schema
bash	1,453	~1,889	Large - detailed examples
task	625	~812	Medium - agent descriptions
multiedit	416	~541	Medium
edit	227	~295	Small-medium
read	203	~264	Small-medium
todoread	177	~230	Small-medium
webfetch	148	~192	Small
grep	112	~146	Small
write	108	~140	Small
glob	94	~122	Small
websearch	77	~100	Small
ls	53	~69	Tiny
lsp-hover	3	~4	Minimal
lsp-diagnostics	3	~4	Minimal
patch	3	~4	Minimal

Default Tool Set (if not specified):

• All 16 tools enabled
• Total: ~6,606 tokens (verified by summing above)

Tool Enable/Disable Logic:

# In agent config:
tools:
  read: true      # Explicitly enable
  write: false    # Explicitly disable
  # If not listed, uses default (usually enabled)

🔥 Critical: Tools are opt-out, not opt-in! If you don't set false, they load by default.

---

Step 3: Message History

Your conversation messages (user + assistant) are added after system prompts and tools.

Token cost:

• Your input: ~1.3 tokens per word
• Previous messages: Accumulates with conversation history

---

Model-Specific Prompts

Why Different Models Get Different Prompts

Each model family has different:

• Instruction-following style
• Output formatting preferences
• Tool-calling conventions
• Context window sizes

Prompt Selection Logic

Source: packages/opencode/src/session/system.ts:25-31

if (modelID.includes("gpt-5")) return [PROMPT_CODEX]
if (modelID.includes("gpt-") || modelID.includes("o1") || modelID.includes("o3")) 
  return [PROMPT_BEAST]
if (modelID.includes("gemini-")) return [PROMPT_GEMINI]
if (modelID.includes("claude")) return [PROMPT_ANTHROPIC]
return [PROMPT_ANTHROPIC_WITHOUT_TODO]  // ← Default

Detailed Prompt Comparison

1. Claude (anthropic.txt) - 1,335 words, ~1,736 tokens

Optimized for:

• Claude 3.5 Sonnet, Claude 3 Opus
• Anthropic's instruction-following style
• Tool use patterns

Key features:

• Concise, direct instructions
• Emphasizes "think step-by-step"
• Specific tool usage examples
• Citations format

Sample excerpt:

You are opencode, an AI assistant specialized in software engineering...
IMPORTANT: Keep responses short and to the point.
When using tools, plan your approach before executing.

---

2. Qwen/Default (qwen.txt) - 1,596 words, ~2,075 tokens

Used by:

• Big Pickle
• Ollama models (llama, qwen, deepseek, etc.)
• Any model not matching other patterns

Optimized for:

• Open-source models
• Models with smaller context windows
• General-purpose instruction following

Key differences from Claude:

• More verbose examples
• Detailed tool explanations
• Explicit formatting instructions
• Less assumption about model capabilities

Sample excerpt:

You are opencode, an interactive CLI tool that helps users with software engineering tasks...
IMPORTANT: Refuse to write code or explain code that may be used maliciously...
When the user asks about opencode, use WebFetch tool to gather information...

🚨 Why this matters for Ollama:

• Ollama models often have 4k-32k context
• 2,075 tokens is 6-50% of total context!
• No caching support = every token costs

---

3. Beast (beast.txt) - 1,904 words, ~2,475 tokens

Used by:

• GPT-4, GPT-4 Turbo
• o1, o1-mini
• o3

Optimized for:

• OpenAI's reasoning models
• Structured thinking
• Chain-of-thought

Key features:

• More detailed reasoning instructions
• Explicit step-by-step guidance
• Tool composition patterns

---

4. Codex (codex.txt) - 3,940 words, ~5,122 tokens

Used by:

• GPT-5 (when available)
• Future advanced models

Optimized for:

• Multi-step complex tasks
• Code generation at scale
• Advanced reasoning

Why so large:

• Comprehensive tool documentation
• Complex workflow examples
• Advanced patterns

---

5. Gemini (gemini.txt) - 2,235 words, ~2,906 tokens

Used by:

• Gemini 1.5 Pro
• Gemini 2.0

Optimized for:

• Google's instruction format
• Gemini-specific features
• Multi-modal capabilities

---

How to Override Model Prompt

Method 1: Agent Prompt Override

---
description: "Custom agent"
mode: primary
prompt: |
  You are a helpful assistant. Be concise.
  You have access to tools for file operations.
---

Result: Your prompt replaces the base model prompt entirely.

Method 2: Command-Line Override

opencode --system "You are a helpful assistant."

Result: Overrides both agent prompt and model prompt.

Method 3: Minimal Prompt (Edit Source)

Edit packages/opencode/src/session/system.ts:

export function provider(modelID: string) {
  // Force minimal for specific models
  if (modelID.includes("ollama")) return ["You are a coding assistant."]
  
  // ... rest of logic
}

---

How Caching Works

What is Prompt Caching?

Concept: AI providers store frequently-used prompt segments and reuse them across requests, charging a reduced rate for cached content.

Which Providers Support Caching?

Source: packages/opencode/src/provider/transform.ts:23-74

function applyCaching(msgs: ModelMessage[], providerID: string): ModelMessage[] {
  const system = msgs.filter((msg) => msg.role === "system").slice(0, 2)
  const final = msgs.filter((msg) => msg.role !== "system").slice(-2)

  const providerOptions = {
    anthropic: {
      cacheControl: { type: "ephemeral" },
    },
    openrouter: {
      cache_control: { type: "ephemeral" },
    },
    bedrock: {
      cachePoint: { type: "ephemeral" },
    },
    openaiCompatible: {
      cache_control: { type: "ephemeral" },
    },
  }
  // ... applies to last 2 system messages and last 2 conversation messages
}

export function message(msgs: ModelMessage[], providerID: string, modelID: string) {
  if (providerID === "anthropic" || modelID.includes("anthropic") || modelID.includes("claude")) {
    msgs = applyCaching(msgs, providerID)
  }
  return msgs
}

Verified Providers:

Provider	Supports Caching	How it Works
Anthropic	✅ Yes	Auto-applied via cacheControl: ephemeral
OpenRouter	✅ Yes (if Anthropic backend)	Auto-applied via cache_control
Bedrock	✅ Yes (if Anthropic models)	Auto-applied via cachePoint
OpenAI-compatible	✅ Maybe	Depends on backend
OpenAI	⚠️ Partial	Uses promptCacheKey (different system)
Ollama	❌ No	Local models don't cache
LM Studio	❌ No	Local server
OpenCode (Big Pickle)	⚠️ Special	Routes through Anthropic API internally

What Gets Cached?

Logic: First 2 system messages + Last 2 conversation messages

const system = msgs.filter((msg) => msg.role === "system").slice(0, 2)
const final = msgs.filter((msg) => msg.role !== "system").slice(-2)

Typical cache structure:

Message 1 (system) - Header + Base Prompt        [CACHED]
Message 2 (system) - Environment + Custom + Tools [CACHED]
...
Message N-1 (user) - Your previous question      [CACHED]
Message N (assistant) - Previous response        [CACHED]
Message N+1 (user) - Current question            [NOT CACHED]

Cache Expiration

Anthropic:

• 5 minutes of inactivity
• Auto-refreshes on each request
• Free cache writes (no cost)
• Cache reads: 10% of input token cost

Example costs (Claude 3.5 Sonnet):

• Input tokens: $3.00 per 1M tokens
• Cached tokens: $0.30 per 1M tokens (10x cheaper!)
• Output tokens: $15.00 per 1M tokens

Why You See High Token Counts

Example session:

Context: 9,800 tokens
Breakdown:
  cache.read: 8,500 tokens  ← From previous request
  input: 1,200 tokens       ← New content this request
  output: 100 tokens        ← Response

Actual cost calculation:

Cache read: 8,500 × $0.30 / 1M = $0.00255
Input: 1,200 × $3.00 / 1M = $0.00360
Output: 100 × $15.00 / 1M = $0.00150
─────────────────────────────────────
Total: $0.00765 (not $0.0294 without cache!)

🔥 Key Insight: High token count ≠ High cost when cached!

Big Pickle Special Case

Why you see cache for Big Pickle (Ollama model):

Big Pickle routes through OpenCode's API, which likely uses Anthropic as the backend. So:

You → OpenCode CLI → OpenCode API → Anthropic API → Big Pickle model
                                    ↑
                              Caching happens here

Evidence:

• You see cache.read tokens
• Token counts match Anthropic's behavior
• Costs are charged (not free like local Ollama)

How to Verify Caching

# Check session cache
cat ~/.local/share/opencode/storage/message/ses_YOUR_SESSION_ID/*.json | \
  jq '.tokens'

# Example output:
{
  "input": 1200,
  "output": 100,
  "cache": {
    "read": 8500,   ← Indicates caching is working
    "write": 0
  }
}

---

Custom Instruction Files

Verified Loading Behavior

Source: packages/opencode/src/session/system.ts:58-115

Local Files (Project-Specific)

Search path: Current directory → Parent → ... → Git root

Files searched (in order):

1. AGENTS.md ← Most common
2. CLAUDE.md ← Legacy
3. CONTEXT.md ← Deprecated

Behavior:

• Searches UP the directory tree
• Stops at first directory containing ANY of these files
• Loads ALL found files from that directory
• Does NOT search subdirectories

Example:

/Users/you/project/
  .opencode/
    AGENTS.md       ← Will be loaded
    CLAUDE.md       ← Will be loaded
  subproject/
    AGENTS.md       ← Will NOT be loaded (parent already matched)

Global Files

Exact paths checked (in order):

1. ~/.config/opencode/AGENTS.md
2. ~/.claude/CLAUDE.md

Behavior:

• Checks exact paths only
• Loads first one found
• Stops after first match

Custom Instructions via Config

In opencode.json:

{
  "instructions": [
    ".opencode/rules/*.md",           // Glob pattern
    "~/global-rules.md",              // Absolute path
    "docs/coding-standards.md"        // Relative path
  ]
}

Behavior:

• Supports globs (*, **)
• Searches UP the tree for relative paths
• Loads ALL matches (no stopping)
• Loads in addition to AGENTS.md/CLAUDE.md

Priority Order

When combining instructions:

1. Local hard-coded files (AGENTS.md, CLAUDE.md)
2. Global hard-coded files
3. Config-specified files

All are concatenated with:

Instructions from: /path/to/file.md
<file content>

How to Disable Custom Instructions

Method 1: Rename files

mv AGENTS.md AGENTS.md.disabled
mv ~/.claude/CLAUDE.md ~/.claude/CLAUDE.md.disabled

Method 2: Move to different location

mkdir .opencode/disabled
mv .opencode/AGENTS.md .opencode/disabled/

Method 3: Remove from config

{
  "instructions": []  // Empty array
}

---

Tool Loading

Default Tool Behavior

Source: All tools enabled by default unless explicitly disabled

Tool Token Costs (Verified)

Total if all enabled: ~6,606 tokens

Expensive tools to consider disabling:

Tool	Tokens	When to Disable
todowrite	1,794	Don't need task management
bash	1,889	Read-only workflows
task	812	Don't use subagents
multiedit	541	Single-file edits only

Cheap tools worth keeping:

Tool	Tokens	Why Keep
read	264	Essential for reading files
write	140	Essential for creating files
edit	295	Essential for modifying files
grep	146	Fast text search
glob	122	Find files by pattern

How to Configure Tools

Global (opencode.json)

{
  "tools": {
    "read": true,
    "write": true,
    "edit": true,
    "bash": true,
    "grep": true,
    "glob": false,
    "ls": false,
    "patch": false,
    "webfetch": false,
    "task": false,
    "multiedit": false,
    "lsp-diagnostics": false,
    "lsp-hover": false,
    "todoread": false,
    "todowrite": false
  }
}

Saves: ~4,856 tokens (keeping only 5 essential tools)

Per-Agent

---
description: "Minimal agent"
tools:
  read: true
  write: true
  edit: true
  # All others implicitly false
---

🚨 IMPORTANT: Must explicitly set false or tools remain enabled!

---

Optimization Strategies

For Anthropic (Claude) - Use Full Context

Rationale: Caching makes large contexts cheap

Recommended:

• Keep all tools enabled
• Include detailed instructions
• Don't worry about context size

Typical setup:

Base prompt: 1,736 tokens
Tools: 6,606 tokens
Environment: 200 tokens
Custom: 500 tokens
───────────────────────
Total: 9,042 tokens

With caching:
First request: 9,042 tokens (~$0.027)
Subsequent: 1,200 input + 8,500 cache read (~$0.006)
Savings: 77% per request!

---

For Ollama (Local Models) - Minimize Everything

Rationale: Limited context, no caching, every token matters

Strategy 1: Disable Base Prompt (Edit Source)

Edit packages/opencode/src/session/system.ts:

export function provider(modelID: string) {
  // Add before other checks:
  if (modelID.includes("ollama") || modelID.includes("llama")) {
    return ["You are a coding assistant. Be concise."]  // 8 tokens!
  }
  
  if (modelID.includes("gpt-5")) return [PROMPT_CODEX]
  // ... rest
}

Saves: ~2,067 tokens (from 2,075 to 8)

Strategy 2: Minimal Tool Set

{
  "tools": {
    "read": true,
    "write": true,
    "edit": true,
    "bash": false,
    "grep": false
  }
}

Saves: ~5,906 tokens (from 6,606 to 700)

Strategy 3: Remove Custom Instructions

mv AGENTS.md AGENTS.md.disabled
mv ~/.claude/CLAUDE.md ~/.claude/CLAUDE.md.disabled

Saves: Varies (typically 200-2,000 tokens)

Strategy 4: Minimal Agent

Create .opencode/agent/ollama.md:

---
description: "Ollama-optimized"
mode: primary
prompt: "Coding assistant. Concise."
tools:
  read: true
  write: true
  edit: true
---

Result:

Base prompt override: 5 tokens
Environment: 40 tokens
Tools: 700 tokens
───────────────────────
Total: ~745 tokens

From 8,000+ to 745 = 91% reduction!

---

For OpenAI (GPT-4) - Balanced

Rationale: Good context window, some caching support

Recommended:

• Use default prompts (well-optimized)
• Enable most tools
• Moderate custom instructions

Typical setup:

Base prompt: 2,475 tokens
Tools: 4,000 tokens (disable heavy ones)
Environment: 200 tokens
Custom: 300 tokens
───────────────────────
Total: 6,975 tokens

---

For Big Pickle - Special Case

Since it routes through Anthropic API:

Option 1: Treat like Claude (use caching)

• Keep full context
• Benefit from caching
• Pay Anthropic rates

Option 2: Optimize for cost

• Disable unnecessary tools
• Minimal custom instructions
• Reduce base prompt via agent override

---

Complete Token Breakdown Examples

Example 1: Default Claude Session

Session: "Fix bug in auth.ts"
Model: claude-sonnet-4
Agent: build (default)
Project: 50 files

TOKEN BREAKDOWN:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Component                    Tokens    Cached
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Header (anthropic_spoof)         12    Yes
Base Prompt (anthropic.txt)   1,736    Yes
Environment Info                 40    Yes
Project Tree (50 files)         150    Yes
AGENTS.md                       245    Yes
~/.claude/CLAUDE.md             356    Yes
───────────────────────────────────────────
System Prompt Total          2,539    Yes

Tools (all 16 enabled)       6,606    Yes
───────────────────────────────────────────
Context Total                9,145    Yes

Your Message                    15    No
───────────────────────────────────────────
TOTAL FIRST REQUEST          9,160

First request cost:  $0.0275
Subsequent (5min):   $0.0050 (82% savings!)

---

Example 2: Optimized Ollama Session

Session: "Fix bug in auth.ts"
Model: ollama/qwen2.5:latest
Agent: ollama-minimal
Project: 50 files

TOKEN BREAKDOWN:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Component                    Tokens    Cached
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Header                            0    No
Agent Prompt Override             8    No
Environment Info                 40    No
Project Tree (50 files)         150    No
No custom instructions            0    No
───────────────────────────────────────────
System Prompt Total             198    No

Tools (3 enabled: read,        700    No
  write, edit)
───────────────────────────────────────────
Context Total                   898    No

Your Message                    15    No
───────────────────────────────────────────
TOTAL EVERY REQUEST             913

Cost: Free (local)
Context usage: 11% of 8k window

---

Example 3: Minimal "HI" Test

Session: "Respond with HI"
Model: big-pickle
Agent: ultra-minimal
Project: 1 file

TOKEN BREAKDOWN:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Component                    Tokens    Cached
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Header                            0    Yes
Base Prompt (qwen.txt)       2,075    Yes
Environment Info                 40    Yes
Project Tree (1 file)             3    Yes
~/.claude/CLAUDE.md              46    Yes
───────────────────────────────────────────
System Prompt Total          2,164    Yes

Tools (ALL disabled)              0    Yes
───────────────────────────────────────────
Context Total                2,164    Yes

Your Message                     4    No
───────────────────────────────────────────
TOTAL                        2,168

With agent override + no tools:
Agent Prompt                      3    Yes
Environment                      40    Yes
Tree                             3    Yes
Tools                            0    Yes
───────────────────────────────────────────
Context Total                   46    Yes
Message                          4    No
───────────────────────────────────────────
TOTAL                           50    

Savings: 97.7% reduction!

---

Quick Reference

Files Always Loaded (if exist)

1. AGENTS.md (local or global)
2. CLAUDE.md (local or global)
3. CONTEXT.md (deprecated, but still loads)
4. Files in config.instructions

Files Never Auto-Loaded

• README.md
• CONTRIBUTING.md
• .opencode/custom.md (unless in instructions)
• Any other .md files

Minimum Viable Configuration

For local models (Ollama):

# .opencode/agent/minimal.md
---
description: "Minimal"
mode: primary
prompt: "Code assistant"
tools:
  read: true
  write: true
  edit: true
---

# Disable global instructions
mv ~/.claude/CLAUDE.md ~/.claude/CLAUDE.md.disabled

# Result: ~750 tokens total

For Claude/hosted:

# Use defaults - caching makes it efficient
# Just create agents with specific tools per task
---
description: "Research agent"
tools:
  read: true
  grep: true
  webfetch: true
---

---

Debugging Context Issues

Check What's Actually Being Loaded

# View session messages
cat ~/.local/share/opencode/storage/message/ses_YOUR_ID/*.json | jq

# Check custom instruction sources
grep -r "Instructions from:" ~/.local/share/opencode/storage/message/

# Count tokens per component
./script/count-agent-tokens.sh your-agent qwen2.5:latest ollama

Common Issues

Issue: "Why 8k tokens for simple query?"
Answer: Base prompt (2,075) + Tools (6,606) = 8,681 tokens

Issue: "Cache not working for Ollama"
Answer: Ollama doesn't support caching (local models)

Issue: "Custom instructions not loading"
Answer: Check exact filenames (case-sensitive), verify path with find

Issue: "Tools still loading after disabling"
Answer: Must set false explicitly, not just omit from config

---

Summary: Key Takeaways

1. Context = Header + Base Prompt + Environment + Custom + Tools
2. Model determines base prompt (1,335-3,940 words)
3. Custom instructions only from specific files (AGENTS.md, CLAUDE.md, etc.)
4. Tools are opt-out, not opt-in (default = all enabled)
5. Caching only works with Anthropic, OpenRouter (Anthropic backend), Bedrock
6. Ollama needs aggressive optimization (no caching, limited context)
7. Claude benefits from full context (caching makes it cheap)
8. Agent prompts override base prompts (when specified)

---

Last Updated: Dec 7, 2025
Verified Against: OpenCode source code packages/opencode/src/session/