Configuration Files

Weave reads from two JSONC configuration files and merges them together before applying. Understanding this merge strategy lets you split global preferences from project-specific settings cleanly.

File Locations

File	Priority	Scope
.opencode/weave-opencode.jsonc	Highest	Current project
~/.config/opencode/weave-opencode.jsonc	Lower	All projects (your defaults)

Both files are optional. If neither exists, Weave uses built-in defaults for all agents.

File Format

Both files use JSONC — JSON with comments. You can annotate your config freely:

{
  // Orchestrator — use the most capable model
  "agents": {
    "loom": {
      "model": "anthropic/claude-opus-4",
      "temperature": 0.1
    }
  }
}

Merge Strategy

When both files exist, Weave merges them with these rules:

Config Element	Strategy
Nested objects (agents, categories, continuation)	Deep merge — project keys override recursively, user keys fill gaps
Arrays (disabled_agents, disabled_tools, etc.)	Union with dedup — entries from both files are combined
Scalars (strings, numbers, booleans)	Project wins

Example: If your user config sets loom.temperature: 0.2 and your project config sets loom.model: "anthropic/claude-opus-4", the merged result has both — temperature: 0.2 from user, model: "anthropic/claude-opus-4" from project.

Config Pipeline

After the two files are merged, the result flows through a 6-phase pipeline:

Phase	Name	Purpose
1	Provider Config	Detect available LLM providers
2	Agent Config	Merge overrides, filter disabled agents, apply prompt_append
3	Tool Config	Filter disabled tools
4	MCP Config	Model Context Protocol setup
5	Command Config	Register slash commands (e.g., /start-work)
6	Skill Config	Skills injected during agent building

INFO

prompt_append is applied in Phase 2. By the time an agent runs, its prompt already includes your appended instructions — no runtime overhead.

Recommended Structure

Use the user config for personal preferences that apply everywhere:

// ~/.config/opencode/weave-opencode.jsonc
{
  // Your preferred models
  "agents": {
    "loom": { "model": "anthropic/claude-opus-4" },
    "thread": { "model": "anthropic/claude-3-haiku" }
  },
  // Hooks you never want
  "disabled_hooks": ["context-window-monitor"]
}

Use the project config for project-specific settings:

// .opencode/weave-opencode.jsonc
{
  "categories": {
    "backend": {
      "description": "Python FastAPI backend",
      "model": "anthropic/claude-opus-4",
      "temperature": 0.1
    }
  },
  "agents": {
    "shuttle": {
      "skills": ["company-standards", "testing"]
    }
  }
}

Continuation Settings

Preview

The continuation config block is currently in preview.

Continuation settings live in the same config files and follow the same deep-merge rules as other nested objects.

// .opencode/weave-opencode.jsonc
{
  "continuation": {
    "recovery": {
      "compaction": true
    },
    "idle": {
      "enabled": false,
      "work": false,
      "workflow": false,
      "todo_prompt": false
    }
  }
}

Use this block to control:

• post-compaction recovery
• idle work nudges
• idle workflow nudges
• fallback todo-finalization prompts

See Execution & Continuation for behavior details, examples, and recommended defaults.