Troubleshooting

A reference for the most common issues encountered when installing, configuring, and using Weave.

Weave Didn't Load

Symptom: OpenCode starts but you don't see "Weave loaded" confirmation, agents like Loom or Tapestry aren't available, or the plugin appears to be ignored.

Check these things:

1. opencode.json exists in your project root (not a subdirectory, not your home directory):

   ls opencode.json

2. Correct format — the plugin field must be an array with the exact package name:

   {
     "plugin": ["@opencode_weave/weave"]
   }

   Common mistakes:

   • Using "plugins" (plural) instead of "plugin"
   • Missing the array brackets: "plugin": "@opencode_weave/weave" ❌
   • Typo in package name: "@opencode/weave" ❌

3. OpenCode version supports plugins — plugins require a recent version of OpenCode. Check your version:

   opencode --version

   Update if needed via opencode.ai.

4. Restart OpenCode — plugin installation happens at startup. If you added Weave to an already-running instance, restart it.

5. Check for npm errors — OpenCode prints errors during plugin installation. If you see an npm error referencing @opencode_weave/weave, check your internet connection or npm registry access.

Agents Not Appearing

Symptom: Weave loaded successfully, but some or all of the agents (Loom, Tapestry, Shuttle, etc.) aren't showing in the agent selector.

Check these things:

1. disabled_agents config — check your weave-opencode.jsonc files for a disabled_agents array:

   cat .opencode/weave-opencode.jsonc
   cat ~/.config/opencode/weave-opencode.jsonc

   If the agent is listed there, remove it or comment it out.

2. Per-agent disable: true — check if the agent is individually disabled:

   // Remove this to re-enable the agent
   "agents": {
     "warp": { "disable": true }
   }

3. For custom agents — naming rules:

   • Name must be lowercase, only letters/numbers/hyphens/underscores
   • Must not collide with built-in names (loom, tapestry, shuttle, pattern, thread, spindle, weft, warp)
   • Must start with a letter (not a number)

4. Config file is valid JSONC — an invalid config file may cause the entire config to be skipped silently. Validate the JSON structure (JSONC allows comments and trailing commas, but braces must be balanced).

Config Not Being Applied

Symptom: You've added settings to weave-opencode.jsonc but Weave isn't picking them up.

Check these things:

1. File is at the correct path:

   • Project config: .opencode/weave-opencode.jsonc (note: .opencode/ subdirectory, not the project root)
   • User config: ~/.config/opencode/weave-opencode.jsonc

2. Valid JSONC syntax — comments and trailing commas are allowed, but watch for:

   • Unmatched braces {}
   • Missing commas between properties
   • Mismatched quote types

3. Merge precedence — project config (.opencode/weave-opencode.jsonc) always wins over user config. If you're setting something in user config but project config overrides it, the user value is ignored.

4. Restart OpenCode — config is read at startup. Changes to config files require restarting OpenCode to take effect.

5. Check for silent failures — some config errors (like referencing a non-existent model ID) don't crash Weave but silently fall back to defaults. Check that model IDs are valid for your configured providers. If you haven't connected a provider yet, run /connect inside OpenCode — see OpenCode provider docs.

/start-work Not Working

Symptom: You type /start-work and nothing happens, or you get an error about no plan found.

Check these things:

1. A plan file exists in .weave/plans/ — /start-work looks for markdown files with unchecked - [ ] checkboxes:

   ls .weave/plans/

   If the directory is empty, you need to ask Loom to create a plan first (by describing a complex task).

2. The plan file has unchecked tasks — if all checkboxes in a plan are already checked (- [x]), there's nothing to execute. /start-work requires at least one - [ ] item.

3. The startWork hook is enabled — check that start-work isn't listed in your disabled_hooks:

   // This would break /start-work — don't do this
   "disabled_hooks": ["start-work"]

4. Plan file follows the expected format — the plan must be a markdown file with GitHub-style task list checkboxes (- [ ] and - [x]). Non-standard checkbox formats won't be recognized.

Tapestry Didn't Continue Automatically

Preview

The automatic continuation settings described in this section are currently in preview. If you need the most predictable behavior, prefer manual resume with /start-work or /run-workflow.

Symptom: You expected execution to resume, but Tapestry stayed idle or stopped after an interruption.

Check these things:

1. Was this compaction recovery or plain idle?

   • By default, Weave resumes after compaction recovery
   • By default, Weave does not nudge a merely idle session to continue

2. Your continuation config:

   {
     "continuation": {
       "recovery": { "compaction": true },
       "idle": {
         "enabled": false,
         "work": false,
         "workflow": false,
         "todo_prompt": false
       }
     }
   }

   If idle.work is false, an idle Tapestry session will stay quiet until you run /start-work again.

3. Relevant hooks are enabled:

   • work-continuation controls work recovery and idle work nudges
   • workflow controls workflow continuation behavior

4. The plan is still resumable — /start-work resumes from the first unchecked task. If every checkbox is already checked, there is nothing left to run.

5. Manual resume is always available — if in doubt, run /start-work again.

See Execution & Continuation for the exact rules.

Todos Were or Weren't Finalized Unexpectedly

Symptom: Leftover in_progress todos were silently completed, or you expected a todo-finalization prompt and did not get one.

Check these things:

1. Direct todo repair can happen silently when Weave can write todos directly. This is expected.

2. Fallback todo prompting is separate — if you want a visible prompt when direct write is unavailable, enable:

   {
     "continuation": {
       "idle": { "todo_prompt": true }
     }
   }

3. The todo-continuation-enforcer hook must be enabled. If it is disabled in disabled_hooks, neither silent repair nor fallback prompting will run.

4. Compaction restoration is separate from todo finalization — compaction-todo-preserver restores todo state after compaction, while todo-continuation-enforcer handles leftover in_progress items.

Skills Not Loading

Symptom: You've assigned skills to agents in config but the agents don't seem to be using them, or you get errors about skills not being found.

Check these things:

1. Skill file is named exactly SKILL.md (uppercase, exact name):

   ✅ .opencode/skills/react/SKILL.md
   ❌ .opencode/skills/react/skill.md
   ❌ .opencode/skills/react/react.md

2. File is in the correct location:

   • Project skills: .opencode/skills/<skill-name>/SKILL.md
   • User skills: ~/.config/opencode/skills/<skill-name>/SKILL.md

3. Valid YAML frontmatter with a name field:

   ---
   name: react-best-practices
   description: React development guidelines
   ---
   
   # React Best Practices
   ...

   The name field is what you reference in config.

4. Skill name in config matches the frontmatter name:

   {
     "agents": {
       "shuttle": {
         "skills": ["react-best-practices"]  // Must match frontmatter name
       }
     }
   }

5. Skill is not in disabled_skills:

   // Remove from here if present
   "disabled_skills": ["react-best-practices"]

Context Window Warnings

Symptom: You see warnings about context window usage during long sessions.

These come from the context-window-monitor hook, which tracks token usage automatically:

• At 80% usage: a warning is printed to help you plan ahead
• At 95% usage: recovery strategies are suggested (e.g., compacting the conversation)

To disable these warnings, add context-window-monitor to your disabled_hooks:

{
  "disabled_hooks": ["context-window-monitor"]
}

See Disabling Features for more about disabling hooks and other components.

Still having issues?

Check the GitHub repository for open issues and discussions. You can also check the Full Configuration Example to see a complete, working config that combines all features.