Agent Configuration

Every Weave agent can be individually configured under agents.<name> in your config. You can override the model, adjust temperature, inject skills, append to the prompt, restrict tools, and more.

Configuration Fields

Field	Type	Description
model	string	Override the LLM used (e.g., "anthropic/claude-opus-4")
fallback_models	string[]	Fallback model chain if primary is unavailable
temperature	number (0–2)	Creativity/determinism dial. Lower = more deterministic
top_p	number (0–1)	Nucleus sampling parameter
variant	string	Select an alternate prompt variant for this agent
category	string	Assign a category for model resolution
skills	string[]	Skills to inject into the agent's prompt
prompt	string	Full replacement of the agent's base prompt
prompt_append	string	Append text to the agent's base prompt
tools	object	Per-tool enable/disable toggles
display_name	string	Override the agent's display name in the UI
disable	boolean	Remove this agent from the system entirely
mode	string	UI selection mode: primary, subagent, or all — see Agent Mode
maxTokens	number	Cap the agent's output token length

prompt vs. prompt_append

prompt completely replaces the agent's built-in prompt — the agent's core behavior is gone. Use prompt_append instead unless you have a strong reason to take full control. See Prompt Append.

Agent Mode

The mode field controls how an agent appears in OpenCode's interface:

Mode	Behavior
primary	Agent appears in the main agent selector in OpenCode's UI. Users can select it directly. It does not appear in the delegation table for other agents to call.
subagent	Agent is only available via delegation from other agents (e.g., Loom delegates to it). It does not appear in the agent selector — users can't select it directly.
all	Agent appears in both the agent selector AND the delegation table. Users can select it directly, and other agents can also delegate to it.

Built-in defaults: Loom and Tapestry are primary. Shuttle is all. Pattern, Thread, Spindle, Weft, and Warp are subagent.

TIP

For custom agents, mode defaults to "subagent" — Loom can delegate to them, but they stay out of the selector unless you explicitly set mode: "all" or mode: "primary".

Available Agents

Config Key	Role
loom	Main orchestrator — the primary user-facing interface that understands requests, routes work, and coordinates results
tapestry	Plan execution orchestrator — used by /start-work to delegate plan tasks to Shuttle, verify results, and track progress
shuttle	Domain specialist worker — handles delegated implementation and analysis tasks
pattern	Strategic planner — produces .weave/plans/ files
thread	Codebase explorer — fast, read-only analysis and search
spindle	External researcher — web fetching and research
weft	Quality reviewer and auditor
warp	Security auditor

Model Resolution Chain

When an agent needs to pick a model, it resolves through this priority chain:

1. Config override — agents.<name>.model (highest priority)
2. UI-selected model — user's current selection in primary/all modes
3. Category model — if the agent has a category assigned with a model
4. Agent's fallback chain — built-in fallback: Anthropic → OpenAI → Google
5. System default — lowest priority

This means you can set agents.loom.model in your user config as a global default, and projects can override it selectively.

Examples

Set models per agent:

{
  "agents": {
    "loom": {
      "model": "anthropic/claude-opus-4",
      "temperature": 0.1
    },
    "thread": {
      "model": "anthropic/claude-3-haiku"  // Cheaper for read-only analysis
    },
    "weft": {
      "model": "openai/gpt-5"
    }
  }
}

Inject skills and append instructions:

{
  "agents": {
    "shuttle": {
      "skills": ["company-standards", "testing"],
      "prompt_append": "Always run `npm test` before marking any task complete."
    },
    "pattern": {
      "skills": ["planning-guidelines"],
      "prompt_append": "Every plan must have at least 3 acceptance criteria per task."
    }
  }
}

Configure fallback models:

{
  "agents": {
    "loom": {
      "model": "anthropic/claude-opus-4",
      "fallback_models": ["openai/gpt-5", "google/gemini-2.0-pro"]
    }
  }
}

Rename agents with display names:

{
  "agents": {
    "loom": { "display_name": "Coordinator" },
    "thread": { "display_name": "Scout" }
  }
}

Disable an agent:

{
  "agents": {
    "warp": {
      "disable": true
    }
  }
}

Tapestry Constraints

Tapestry is specifically the /start-work plan execution coordinator: it delegates plan tasks to Shuttle agents via the Task tool rather than implementing code directly itself.

Display Names

Every built-in agent can be given a custom display name via the display_name field. The display name appears in the UI header, agent responses, and prompt routing — while the config key (loom, thread, etc.) stays the same for all configuration purposes.

This is useful for:

• Localization — name agents in your native language
• Personalization — give agents names that match your team's vocabulary
• Theming — create a consistent naming theme across your setup

Japanese Localization

{
  "agents": {
    "loom": { "display_name": "織機 (メインオーケストレーター)" },
    "thread": { "display_name": "糸 (コード探索)" },
    "pattern": { "display_name": "型紙 (設計プランナー)" },
    "shuttle": { "display_name": "杼 (ドメイン専門家)" },
    "spindle": { "display_name": "紡錘 (外部リサーチ)" },
    "weft": { "display_name": "横糸 (レビュアー)" },
    "warp": { "display_name": "経糸 (セキュリティ)" }
  }
}

Team Role Names

{
  "agents": {
    "loom": { "display_name": "Tech Lead" },
    "pattern": { "display_name": "Architect" },
    "shuttle": { "display_name": "Senior Dev" },
    "thread": { "display_name": "Analyst" },
    "weft": { "display_name": "QA Lead" },
    "warp": { "display_name": "SecOps" }
  }
}

Config Key vs Display Name

The config key (e.g., loom, thread) is always used in configuration files, CLI commands, and internal routing. The display_name only affects what you see in the UI. You can rename agents without breaking any config references, skills, or delegation rules.

Custom Agents

Beyond configuring the built-in agents, you can define entirely new agents via the custom_agents config block. Custom agents support all the same model resolution, skills, and tool permissions — plus additional fields like display_name, category, cost, and delegation triggers.

{
  "custom_agents": {
    "docs-writer": {
      "display_name": "Docs Writer",
      "description": "Technical documentation specialist",
      "model": "anthropic/claude-sonnet-4",
      "prompt": "You are a technical documentation expert.",
      "mode": "subagent"
    }
  }
}

Custom agents appear alongside built-ins in the delegation table, and Loom can route tasks to them automatically based on their triggers. They only appear in the selector if their mode is primary or all.

Full Guide

See Custom Agents for the complete reference, including naming rules, prompt sources, tool permissions, and practical examples.