Custom Agents

Weave ships with a set of built-in agents (Loom, Tapestry, Shuttle, Pattern, Thread, Spindle, Weft, Warp), and you can define entirely new ones via the custom_agents config. Custom agents appear alongside built-ins — Loom can delegate to them, they show up in the agent selector, and they participate in model resolution like any other agent.

Quick Start

Add a custom_agents block to your config:

{
  "custom_agents": {
    "docs-writer": {
      "display_name": "Docs Writer",
      "description": "Technical documentation specialist",
      "model": "anthropic/claude-sonnet-4",
      "prompt": "You are a technical documentation expert. Write clear, concise docs with examples. Use active voice and present tense.",
      "mode": "subagent"
    }
  }
}

That's it — Loom will now see docs-writer as a delegatable agent and can route documentation tasks to it.

Configuration Fields

Field	Type	Default	Description
prompt	string	—	Inline system prompt text
prompt_file	string	—	Path to a .md file containing the system prompt (relative to config directory)
model	string	—	Model to use (e.g., "anthropic/claude-sonnet-4")
fallback_models	string[]	—	Fallback model chain if primary is unavailable
display_name	string	agent key	Display name shown in the UI
description	string	display name	Description shown alongside the agent
mode	"subagent" | "primary" | "all"	"subagent"	UI visibility — see Agent Mode for details
category	"exploration" | "specialist" | "advisor" | "utility"	"utility"	Category for Loom's delegation table
cost	"FREE" | "CHEAP" | "EXPENSIVE"	"CHEAP"	Cost classification shown in Loom's tool selection
temperature	number (0–2)	—	Sampling temperature
top_p	number (0–1)	—	Nucleus sampling parameter
maxTokens	number	—	Maximum output tokens
tools	object	all enabled	Per-tool enable/disable toggles
skills	string[]	—	Skills to inject into this agent's prompt
triggers	object[]	auto-generated	Delegation triggers for Loom integration

Also Available for Built-in Agents

display_name isn't just for custom agents — you can rename any built-in agent too. See Display Names for examples including localization and theming.

Agent Naming Rules

Agent names must:

• Start with a lowercase letter
• Contain only lowercase letters, numbers, hyphens, and underscores
• Not collide with built-in agent names (loom, tapestry, shuttle, pattern, thread, spindle, weft, warp)

✅ docs-writer
✅ security_reviewer
✅ api-tester-v2
❌ DocsWriter       (uppercase)
❌ 2fast            (starts with number)
❌ loom             (collides with built-in)

Prompt Sources

You can provide the agent's system prompt in three ways:

1. Inline Prompt

{
  "custom_agents": {
    "api-tester": {
      "prompt": "You are an API testing specialist. Write comprehensive test suites for REST APIs using the project's testing framework."
    }
  }
}

2. Prompt File

Store the prompt in a separate .md file for longer, more complex instructions:

{
  "custom_agents": {
    "api-tester": {
      "prompt_file": ".opencode/prompts/api-tester.md"
    }
  }
}

The path is resolved relative to the config file's directory. Absolute paths and paths that escape the project directory (e.g., ../../etc/passwd) are rejected.

3. Skills

Inject reusable skill modules — they get prepended to the prompt:

{
  "custom_agents": {
    "api-tester": {
      "skills": ["testing", "api-design"],
      "prompt": "Additional instructions specific to this agent."
    }
  }
}

Combining Sources

When both prompt_file and prompt are specified, prompt_file takes priority. Skills are always prepended before the main prompt, regardless of source.

Delegation Triggers

Delegation triggers tell Loom when and why to delegate to your custom agent. If you don't specify triggers, Weave generates a default:

// Auto-generated trigger
{ "domain": "Custom", "trigger": "Tasks delegated to Docs Writer" }

For better Loom integration, define explicit triggers:

{
  "custom_agents": {
    "docs-writer": {
      "display_name": "Docs Writer",
      "triggers": [
        { "domain": "Documentation", "trigger": "README updates, API docs, user guides, changelog entries" },
        { "domain": "Technical Writing", "trigger": "Architecture decision records, design documents" }
      ]
    }
  }
}

These appear in Loom's delegation table, helping it route tasks accurately.

Tool Permissions

By default, custom agents have access to all tools. Restrict access with the tools field:

{
  "custom_agents": {
    "read-only-analyzer": {
      "prompt": "Analyze code and produce reports. Never modify files.",
      "tools": {
        "write": false,
        "edit": false,
        "bash": false
      }
    }
  }
}

Available tools: write, edit, bash, glob, grep, read, task, call_weave_agent, webfetch, todowrite, skill.

Unknown Tools

Specifying a tool name not in the list above will cause an error at startup. This prevents typos from silently failing.

Model Resolution

Custom agents follow the same model resolution chain as built-in agents:

1. Config model field (highest priority)
2. UI-selected model (only in primary or all mode)
3. Custom fallback chain via fallback_models
4. System default model (lowest priority)

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

Examples

Parallel Security Reviewer

Add a second security reviewer that uses a different model, so you get two independent security perspectives:

{
  "custom_agents": {
    "security-reviewer-alt": {
      "display_name": "Security Reviewer (GPT)",
      "description": "Independent security review using OpenAI",
      "model": "openai/gpt-5",
      "category": "advisor",
      "cost": "EXPENSIVE",
      "prompt": "You are a security auditor. Review code for vulnerabilities including injection attacks, authentication flaws, data exposure, and insecure dependencies. Be thorough and skeptical.",
      "tools": {
        "write": false,
        "edit": false,
        "bash": false
      },
      "triggers": [
        { "domain": "Security", "trigger": "Independent security review from a different model perspective" }
      ]
    }
  }
}

Database Migration Specialist

{
  "custom_agents": {
    "db-migrate": {
      "display_name": "DB Migration",
      "description": "Database schema and migration specialist",
      "model": "anthropic/claude-sonnet-4",
      "category": "specialist",
      "cost": "CHEAP",
      "skills": ["database-patterns"],
      "prompt_file": ".opencode/prompts/db-migration.md",
      "triggers": [
        { "domain": "Database", "trigger": "Schema changes, migrations, query optimization, index management" }
      ]
    }
  }
}

Lightweight Linter Agent

A fast, cheap agent for style checks:

{
  "custom_agents": {
    "linter": {
      "display_name": "Style Checker",
      "description": "Fast code style and formatting checks",
      "model": "anthropic/claude-3-haiku",
      "category": "utility",
      "cost": "FREE",
      "prompt": "Check code for style issues: naming conventions, formatting, import ordering, dead code. Report issues concisely. Do not fix — only report.",
      "tools": {
        "write": false,
        "edit": false,
        "bash": false
      },
      "triggers": [
        { "domain": "Code Quality", "trigger": "Style checks, linting, formatting review" }
      ]
    }
  }
}

Custom Agents are Additive

Custom agents add to the system — they never replace built-in agents. If you want to change a built-in agent's behavior, use Agent Configuration instead.