Configuration Files

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

File Locations

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

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

Directory Layout

~/.weave/                    # Global config root
├── config.weave             # Global agent/category/workflow definitions
└── prompts/                 # Global prompt files
    └── my-agent.md

.weave/                      # Project config root
├── config.weave             # Project agent/category/workflow definitions
├── prompts/                 # Project prompt files
│   ├── loom.md
│   ├── shuttle.md
│   └── custom-agent.md
├── plans/                   # Plan files (created by Pattern agent)
└── workflows/               # Additional workflow files (optional)

File Format

Both files use the .weave DSL, a block-structured, declarative configuration language. It is not JSON or YAML.

# Orchestrator - use the most capable model
agent loom {
  models ["anthropic/claude-opus-4"]
  temperature 0.1
}

See DSL Syntax for the full language reference.

Merge Strategy

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

Config Element	Strategy
Named blocks (agent, category, workflow)	Deep merge: project keys override recursively, global keys fill gaps
Arrays (models, skills, patterns)	Union-merge: entries from both files are combined
Scalars (strings, numbers, booleans)	Project wins

Example: If your global config sets temperature 0.2 on an agent and your project config sets models [...] on the same agent, the merged result has both.

Recommended Structure

Use the global config for personal preferences that apply everywhere:

# ~/.weave/config.weave

agent loom {
  models ["anthropic/claude-opus-4"]
}

agent thread {
  models ["anthropic/claude-3-haiku"]
}

disable hooks ["context-window-monitor"]

Use the project config for project-specific settings:

# .weave/config.weave

category backend {
  description "Python FastAPI backend"
  models ["anthropic/claude-opus-4"]
  temperature 0.1
}

agent shuttle {
  skills ["company-standards", "testing"]
}

Continuation Settings

Continuation settings live in the same config file and follow the same merge rules as other blocks.

continuation {
  recovery {
    compaction true
  }
  idle {
    enabled false
    work false
    workflow false
  }
}

Use this block to control:

• Post-compaction recovery behavior
• Idle work nudges
• Idle workflow nudges

See Execution and Continuation for behavior details and recommended defaults.