Configuration

Configure Weave with weave-fabric.jsonc — per-agent model overrides, category-based dispatch, hook/tool/skill toggles, background concurrency, skill discovery paths, and experimental settings. Layered user → project merging.

Weave runs with sensible defaults out of the box; you only need a config file when you want to override something. Configuration lives in JSONC files (comments and trailing commas are allowed) and merges in two layers.

File locations

Level	Path	Priority
Project	`.fabric/weave-fabric.jsonc` (or `.json`)	Highest — wins on merge
User	`~/.config/fabric/weave-fabric.jsonc` (or `.json`)	Defaults

Merge strategy

Nested objects (agents, categories): deep-merge — project keys override user keys recursively.
Arrays (disabled_*): union with deduplication — both lists combine.
Scalars: project value wins.

JSON schema

The canonical schema lives in the Weave repo at schema/weave-config.schema.json. Reference it from $schema to get autocomplete and validation in your editor:

{
  "$schema": "https://raw.githubusercontent.com/Fabric-Pro/fabric-weave/main/schema/weave-config.schema.json",
  // …
}

For reproducible setups pin to a release tag (/v0.8.6/schema/…) instead of main.

Full example

{
  "$schema": "https://raw.githubusercontent.com/Fabric-Pro/fabric-weave/main/schema/weave-config.schema.json",

  // Override behaviour per agent. Keys are lowercase agent names.
  // Subagents inherit Loom's model unless explicitly set here.
  "agents": {
    // Primary agents — handle the user-facing conversation
    "loom": {
      "model": "anthropic/claude-opus-4",
    },
    "tapestry": {
      "model": "anthropic/claude-sonnet-4",
    },

    // Subagents — pin to faster/cheaper models for high-volume work
    "thread":  { "model": "anthropic/claude-haiku-4" },
    "spindle": { "model": "anthropic/claude-haiku-4" },
    "pattern": { "model": "anthropic/claude-sonnet-4" },
    "weft":    { "model": "anthropic/claude-sonnet-4" },
    "warp":    { "model": "anthropic/claude-sonnet-4" },
    "shuttle": { "model": "anthropic/claude-sonnet-4" },
  },

  // Category-based dispatch — Loom routes work into a category and
  // Shuttle picks up the matching model + tools.
  "categories": {
    "visual-engineering": {
      "description": "UI work, design systems, frontend polish",
      "model": "google/gemini-3-pro",
      "temperature": 0.3,
    },
  },

  // Selective disabling
  "disabled_hooks":  [],
  "disabled_agents": [],
  "disabled_tools":  [],
  "disabled_skills": [],

  // Background agent concurrency
  "background": {
    "defaultConcurrency": 5,
  },
}

Agent overrides

Each entry in agents accepts the following fields:

Field	Type	Purpose
`model`	`"provider/model"`	Override the model used by this agent.
`temperature`	number `0–2`	Override sampling temperature.
`variant`	string	Use a named prompt variant.
`skills`	string[]	Inject named skills into this agent's system prompt.
`prompt_append`	string	Append text to the agent's system prompt (rules, project conventions, etc.).
`display_name`	string	Custom label shown in the Fabric UI. Internal references still use the config key.
`tools`	`{ tool: boolean }`	Per-tool allow/deny. e.g. `{ "bash": true, "write": false }`.
`disable`	boolean	Remove the agent from the UI entirely.

Example — pin Pattern to a different model

{
  "agents": {
    "pattern": {
      "model": "openai/gpt-5",
      "temperature": 0.5,
    },
  },
}

Example — rename agents in the UI

display_name only changes the UI label; everything else (workflow references, disabled_agents, prompt text) keeps using the original config key.

{
  "agents": {
    "loom":    { "display_name": "織機 (メインオーケストレーター)" },
    "thread":  { "display_name": "糸 (コードベースエクスプローラー)" },
    "pattern": { "display_name": "設計 (戦略プランナー)" },
    "weft":    { "display_name": "レビュー担当" },
  },
}

Valid agent keys

Key	Default display name	Role
`loom`	Loom (Main Orchestrator)	Primary orchestrator
`tapestry`	Tapestry (Execution Orchestrator)	Plan executor
`pattern`	pattern	Strategic planner
`thread`	thread	Codebase explorer
`spindle`	spindle	External researcher
`weft`	weft	Reviewer / auditor
`warp`	warp	Security auditor
`shuttle`	shuttle	Category specialist

See Agents for what each one is best at.

Disabling features

Each disabled_* array is a simple block-list. Names match the canonical IDs from the plugin.

{
  "disabled_agents": ["spindle"],
  "disabled_hooks":  ["context-window-monitor", "keyword-detector"],
  "disabled_tools":  ["webfetch"],
  "disabled_skills": ["legacy-skill"],
}

Built-in hooks you can disable:

context-window-monitor — warns when token usage approaches limits.
write-existing-file-guard — prevents agents from overwriting files they haven't read.
rules-injector — injects AGENTS.md rules when an agent enters a directory.
first-message-variant — applies prompt variants on session start.
keyword-detector — switches behaviour based on keywords in messages.

Background agents

Weave runs background subagents in parallel via a BackgroundManager. Tune the limits to match your provider's rate limits.

{
  "background": {
    "defaultConcurrency": 5,        // Max in-flight background tasks
    "providerConcurrency": {        // Per-provider caps
      "anthropic": 5,
      "openai": 3,
    },
    "modelConcurrency": {           // Per-model caps (most specific wins)
      "claude-sonnet-4-20250514": 10,
    },
    "staleTimeoutMs": 60000,        // Reap tasks idle for this long
  },
}

Skills

Skills are markdown SKILL.md files that get prepended to an agent's system prompt. Weave discovers them in three scopes: builtin (shipped with the plugin), user (~/.config/fabric/skills/), and project (.fabric/skills/). To add custom roots:

{
  "skill_directories": [".custom-skills"],
  "agents": {
    "pattern": {
      "skills": ["planning-guidelines"],
    },
    "shuttle": {
      "skills": ["react-best-practices", "api-design"],
    },
  },
}

skill_directories paths are project-relative and rejected if absolute or containing ...

Experimental settings

{
  "experimental": {
    "plugin_load_timeout_ms": 5000,            // Max time Weave waits during init
    "context_window_warning_threshold": 0.8,   // Fraction at which the monitor warns
    "context_window_critical_threshold": 0.95, // Fraction at which the monitor escalates
  },
}

Model resolution order

When Weave needs to decide which model an agent uses, it walks this priority chain:

agents.<name>.model from your config.
The model picked in the Fabric UI (primary/all-mode agents only).
The agent's category model (Shuttle only).
A provider fallback chain — anthropic → openai → google for most agents.
The system default.

Subagents inherit Loom's model when nothing else is set, so a single override on loom propagates to the whole team unless individually pinned.

Recipes

Pin every subagent to a single provider

{
  "agents": {
    "thread":  { "model": "kimi-for-coding/k2p5" },
    "spindle": { "model": "kimi-for-coding/k2p5" },
    "pattern": { "model": "kimi-for-coding/k2p5" },
    "weft":    { "model": "kimi-for-coding/k2p5" },
    "warp":    { "model": "kimi-for-coding/k2p5" },
  },
}

Lock down `@shuttle` so it can read but not write

{
  "agents": {
    "shuttle": {
      "tools": {
        "write": false,
        "edit": false,
        "bash": false,
      },
    },
  },
}

Project-scoped overrides only

Drop a .fabric/weave-fabric.jsonc into a single repo with the overrides — they merge on top of your user-level defaults without affecting other projects.

// .fabric/weave-fabric.jsonc — repo-specific
{
  "agents": {
    "loom": {
      "prompt_append": "Always run `bun typecheck` before declaring work done.",
    },
  },
}

Next: Agents — what each agent does and when Loom delegates to it.