Upgrading from legacy Weave

This guide is for anyone using the legacy OpenCode plugin, @opencode_weave/weave. That plugin is no longer maintained. Weave now lives at weave-io/weave, and it runs on OpenCode, OpenCode 2, and Claude Code.

The upgrade converts your existing config, so you keep your agent overrides, custom agents, descriptions, and prompts. Most setups take a few minutes.

What changes

Weave keeps the same eight agents (Loom, Tapestry, Shuttle, Pattern, Thread, Spindle, Weft, and Warp) and the same plan-then-execute workflow. The package names and the config format are different:

	Legacy Weave	Weave
OpenCode plugin	`@opencode_weave/weave`	`@weaveio/weave-adapter-opencode`
CLI	none	`@weaveio/weave-cli` (the `weave` command)
Project config	`.opencode/weave-opencode.jsonc`	`.weave/config.weave`
User config	`~/.config/opencode/weave-opencode.jsonc`	`~/.weave/config.weave`
Config format	JSONC	`.weave` DSL
Harnesses	OpenCode	OpenCode, OpenCode 2, Claude Code
Start a plan	`/start-work`	`/weave:start` (`/start-work` still works)

Step 1: Install the Weave CLI

The CLI runs on Bun, not Node.js.

bun add --global @weaveio/weave-cli@0.2.0
weave --help

Step 2: Migrate your config

weave init migrate converts a legacy JSONC config into the .weave DSL. Run it once for each config you have:

# Project config: .opencode/weave-opencode.jsonc -> .weave/config.weave
# (run this from each project root)
weave init migrate --scope local

# User config: ~/.config/opencode/weave-opencode.jsonc -> ~/.weave/config.weave
weave init migrate --scope global

Before you run it:

Give every category a description. Categories need one now, and migration skips a category without one, along with its shuttle-<category> agent. Legacy accepted a description on categories too, so add it to the legacy file first.
Only .jsonc files are picked up. If your config is weave-opencode.json, rename it to weave-opencode.jsonc first. Plain JSON is valid JSONC, so the contents don’t need to change.
Your legacy file isn’t touched. Migration only reads it, so you can go back if you need to.
Comments and trailing commas are fine. If the file can’t be parsed at all, migration exits with code 1 and writes nothing.

Migration shows a preflight summary before it writes anything, and it lists every field it skipped. See what carries over and what doesn’t.

If you never customized the legacy config, there’s nothing to migrate. Run weave init --scope local --yes to create a fresh config instead.

Step 3: Validate the result

weave validate

Run it from the project root, with no flags, so it checks the merged project and user config. It exits non-zero and names any agent the adapters can’t register, such as an agent with no prompt or a missing prompt_file. Fix what it reports and run it again until it passes.

To see an agent’s composed prompt:

weave prompt inspect loom

Step 4: Swap the plugin in `opencode.json`

Remove the legacy plugin and add the Weave adapter. Don’t run both at the same time.

{
  "plugin": ["@opencode_weave/weave"]
  "plugin": ["@weaveio/weave-adapter-opencode@0.2.0"]
}

Step 5: Restart OpenCode and verify

opencode debug config

The output should list @weaveio/weave-adapter-opencode and no longer list @opencode_weave/weave. Your agents, including custom agents and shuttle-<category> agents, appear under agent.

Step 6: Clean up

Once everything works, delete the legacy config files:

rm -f .opencode/weave-opencode.jsonc .opencode/weave-opencode.json
rm -f ~/.config/opencode/weave-opencode.jsonc ~/.config/opencode/weave-opencode.json

Keep the .weave/ directory. Weave stores its config there, and it reads existing plans from .weave/plans/.

What carries over

Legacy field	Becomes
`agents.<name>` (builtin overrides)	`agent <name> { ... }`
`custom_agents.<name>`	`agent <name> { ... }`
Custom agent `description`	`description "..."`, falling back to `display_name`
Custom agent `prompt`	`prompt "..."`
Custom agent `prompt_file`	The file is copied to `.weave/prompts/<agent>.md` and referenced by `prompt_file`
`model` + `fallback_models`	`models [...]`, in the same order
`tools`	`tool_policy { ... }` (known tools only)
`categories.<name>`	`category <name> { ... }`
`disabled_agents`, `disabled_hooks`, `disabled_skills`	`disable agents/hooks/skills [...]`
`log_level`	`settings { log_level ... }`

A few details:

prompt_file paths are read the way legacy read them: relative to .opencode/ for a project config, or ~/.config/opencode/ for the user config. As in legacy, a readable prompt_file wins over an inline prompt.
Models written as provider/model (for example anthropic/claude-sonnet-4-5) are kept.
A custom agent left with no prompt is skipped with a warning, because the adapters can’t register an agent without one.
A custom agent that reuses a builtin name, such as loom, is skipped with a warning rather than silently replacing the builtin.
A category with no description is skipped with a warning (a non-empty category description is required; category skipped). Add a description to the category and migrate again.

What doesn’t carry over

Each of these is reported as a warning after migration and recorded as a comment at the top of the migrated config.weave:

Legacy setting	What to do
`skill_directories`	Move or symlink the skills into `.opencode/skills/`.
`disabled_tools`	Use `tool_policy` on the agent or category.
Agent and custom agent `skills`	Not converted.
Custom agent `triggers` (`{ domain, trigger }` objects)	Add string triggers to the agent if Loom should route to it.
Category `patterns`	Categories route by `description` and triggers. See Routing.
`workflows`	Define workflows with the DSL workflow syntax.
`continuation`	Use the DSL `continuation` block if you need it.
`background`, `tmux`, `experimental`, `analytics`	No equivalent.
Builtin agent `prompt` and `prompt_file` overrides	Not converted. Legacy ignored them too, so the builtin prompt stays in effect.
`variant` on an agent or category	Not converted. The DSL supports `variant`, so add it back to the agent or category by hand.
`top_p`, `maxTokens`, `modelOptions`, `review_models`, `cost`, `category`, `disable` on an agent or category	No current equivalent.

Here’s the start of a migrated config with skipped fields:

# Migrated from legacy OpenCode JSONC config
# Scope: local
# Generated by: weave init migrate
#
# Legacy fields that were not migrated:
#   - skill_directories: legacy skill_directories are not migrated; move or symlink those skills into a directory your harness discovers (for OpenCode, .opencode/skills/)
#   - custom_agents.code-reviewer.triggers: legacy structured triggers ({ domain, trigger }) are not migrated; add string triggers to the agent if Loom should route to it
#   - categories.backend.patterns: patterns are removed; describe routing with category description and string triggers

Migration never adds settings you didn’t have. If nothing in a legacy config converts, config.weave holds only these comments.

Differences you’ll notice

Default models. For an agent with no configured model, legacy picked one from a built-in list, trying github-copilot/*, then anthropic/*, then openai/* models you had available. Weave uses your OpenCode model instead. To pin an agent, add models ["provider/model"]. See Model Resolution.
Category routing. Categories no longer match file paths. The orchestrator routes by each category’s description and triggers.
Plan command. /weave:start starts a plan. /start-work still works as an alias.

Troubleshooting

“No legacy config found”

No legacy config found for scope "local".
Expected: /project/.opencode/weave-opencode.jsonc

Nothing to migrate.

Migration looks only for weave-opencode.jsonc in the scope’s directory. If your file is weave-opencode.json, rename it to .jsonc. If you’re in a subdirectory, run the command from the project root. For the user config, use --scope global.

“Migration failed: The legacy config could not be converted”

Migration failed: The legacy config could not be converted, so nothing was written.
  • <source>: failed to parse legacy JSONC source; no fields could be converted

The legacy file isn’t valid JSONC, so migration stopped without writing anything. Fix the syntax error and run the command again. OpenCode would have failed to load this file too.

`weave validate` says an agent “cannot be registered by harness adapters”

agent "reviewer" cannot be registered by harness adapters: Agent "reviewer" must define either prompt or prompt_file.

Give the agent a prompt or a prompt_file, or make sure its prompt_file exists under .weave/prompts/. Adapters skip agents like this, so they’d otherwise be missing from OpenCode.

An agent fails with `ProviderModelNotFoundError`

You’re running an older adapter. Pin @weaveio/weave-adapter-opencode@0.2.0 or later in opencode.json, then restart OpenCode.

Agents appear twice, or legacy behavior persists

Both plugins are loaded. Remove @opencode_weave/weave from the plugin list in every opencode.json and opencode.jsonc, including ~/.config/opencode/, then restart OpenCode.

For anything else, see Troubleshooting or open an issue on weave-io/weave.