defineVector() API reference

Define one Vector Configuration from its identity and a builder-bound Context callback that returns the complete Extension Plan for each activation.

Import defineVector() from @evilkiwi/vector.

function defineVector(definition: VectorDefinition): Plugin.Plugin;

VectorDefinition

defineVector() does not accept runtimeConfig. Pass Runtime Configuration metadata to createVectorBuilder(), then call that builder’s defineVector() method. The root helper and createVectorBuilder() without options provide no-config behavior.

defineVector() captures id and build when called. It returns the pinned Plugin.Plugin type from OpenCode 2. Default-export that value as the OpenCode Plugin Entrypoint.

ExtensionPlan

The build(context) callback may return arrays for all Extension Definition domains:

agents, catalogProviders, commands, integrationMethods, integrations, mcpServers, models, references, skills, tools, and webSearchProviders.

It may also select defaultAgent, defaultModel, and defaultWebSearchProvider. A default must name a compatible extension in the same completed Snapshot. defaultWebSearchProvider may be false to select the host’s disabled value. Omitted arrays materialize as empty arrays.

instructionFiles

instructionFiles?: (string | URL)[] selects ordered Configuration Package files that supply Global Instructions. Use a file: URL to select a file relative to the current module:

const plan: ExtensionPlan = {
  instructionFiles: [new URL('../instructions/global.md', import.meta.url)],
};

String entries must be absolute paths or begin with ~/; URL strings, globs, and relative paths remain invalid. URL objects must use file:. Other URL schemes, directories, and missing or unreadable files fail activation before any host transform registration.

Vector converts file URL objects with Node’s fileURLToPath, expands ~/ in strings, resolves each source to its canonical regular file, deduplicates canonical paths by first occurrence, and reads the retained files as UTF-8 in order. Symlink aliases therefore contribute one block, while distinct files with identical content each contribute a block. A zero-byte file contributes nothing.

Each retained block has this exact shape, where <exact content> is not trimmed or normalized:

Instructions from: <canonical path>
<exact content>

Vector joins the blocks with \n\n. The agent transform applies selected Agent Definitions first, preserves each agent’s existing system, appends the joined Global Instructions to every built-in, host-defined, and Vector-defined agent returned by OpenCode, then selects defaultAgent. Replay does not append an identical trailing block again. Omitting instructionFiles or returning an empty array leaves agent systems unchanged.

Read createVectorBuilder() to bind inferred Runtime Configuration and computed Context types across configuration and extension callbacks. See Extensions for helper inputs and identity behavior.