Customization Overview
Looking to install Weave? Start with the Getting Started guide.
Weave gives you a layered, additive customization system for every agent. You never need to fork or modify core agent prompts — all customization is done through configuration files and skill files that merge on top of built-in defaults.
How It Works
Weave customization is built on one key principle: everything is additive. You can:
- Append instructions to any agent's prompt without touching its base prompt
- Inject domain-specific knowledge as reusable skill files
- Create domain-optimized variants of Shuttle (the coding specialist) via categories
- Override the model, temperature, and other parameters per agent
- Define entirely new custom agents with their own prompts, models, and tools
- Disable agents, tools, and hooks you don't need
- Reshape the delegation workflow to fit your team's process
Config File Locations
Weave reads from two config files, merged in order:
| Location | Priority | Purpose |
|---|---|---|
.opencode/weave-opencode.jsonc | Highest | Project-specific overrides |
~/.config/opencode/weave-opencode.jsonc | Lower | User-level defaults |
Both files use JSONC format (JSON with comments). If a key exists in both files, the project config wins. See Configuration Files for merge details.
Customization Mechanisms
| Mechanism | Description |
|---|---|
| Prompt Append | Add instructions to any agent without replacing its base prompt |
| Skills | Inject reusable domain knowledge as SKILL.md files |
| Categories | Define domain-optimized Shuttle variants with custom models and settings |
| Agent Configuration | Per-agent model, temperature, tools, and more |
| Custom Agents | Define entirely new agents with custom prompts, models, and delegation triggers |
| Disabling Features | Remove agents, tools, or hooks you don't need |
| Execution & Continuation | Understand /start-work, compaction recovery, idle nudges, and todo finalization |
| Workflow Customization | Recipes for reshaping the agent workflow |
| Analytics | Local session tracking, project fingerprinting, and workflow insights |
Agent Roster
| Agent | Role |
|---|---|
loom | Main orchestrator — plans and delegates work |
tapestry | Execution orchestrator — works through plans step by step |
shuttle | Domain specialist — handles delegated coding tasks |
pattern | Strategic planner — produces .weave/plans/ files |
thread | Codebase explorer — fast, read-only analysis |
spindle | External researcher — web fetching and research |
weft | Quality reviewer and auditor |
warp | Security auditor |
Start Here
If you're new to Weave customization, start with Prompt Append — it's the simplest mechanism and works immediately. Then explore Skills for reusable, shareable domain knowledge.