@witness-ai/opencode

@witness-ai/opencode

OpenCode plugin for witness. It reconciles OpenCode's local session database on startup and when a session goes idle, and starts witness distillation only through the CLI's laptop-friendly auto-start gate.

Supported platforms

Operating system	Architecture	Installed binary package
macOS	Apple Silicon (darwin/arm64)	@witness-ai/opencode-darwin-arm64
Linux	x86-64 (linux/x64)	@witness-ai/opencode-linux-x64
Windows	x86-64 (win32/x64)	@witness-ai/opencode-win32-x64
Windows	ARM64 (win32/arm64)	@witness-ai/opencode-win32-arm64

These are the only platforms supported by the npm distribution. macOS Intel and Linux ARM are not supported; the CLI exits with a clear supported-platform message on those systems.

Windows requires OpenCode 1.18.0 or newer. If you prefer a self-contained install with the embedding model already included — no first-run download — use the zip from the latest release instead.

Install

Add the npm plugin to your OpenCode config. OpenCode installs the package automatically with Bun on startup, and the plugin auto-registers mcp.witness if you have not already defined one:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@witness-ai/opencode"]
}

To test a prerelease, pin an explicit version instead of the unversioned package name — e.g. "plugin": ["@witness-ai/opencode@0.8.0-beta.1"]. Use a real published version; the beta dist-tag is not kept current, so pinning it can silently install something several releases old.

Optional: install it globally if you also want a witness CLI on your shell PATH:

npm install -g @witness-ai/opencode

Optional: run the CLI ad hoc without a global install:

npm exec --yes --package=@witness-ai/opencode -- witness doctor

The main package includes the plugin, CLI wrapper, and prompts. npm installs one optional platform package containing the matching witness binary; it does not download binaries for other operating systems or architectures. The first embedding-model download is about 470MB into the witness data directory (assets/e5-small). npm install only installs the packages; the OpenCode plugin starts the model download when OpenCode next starts. Keep OpenCode running until the first download finishes. If OpenCode stops early, the plugin stops its downloader and retries later with bounded backoff. Set WITNESS_BIN to override the platform package binary.

After the download completes, verify the model, OpenCode runner, archive, and queue:

npm exec --yes --package=@witness-ai/opencode -- witness doctor
npm exec --yes --package=@witness-ai/opencode -- witness status

Upgrade note: Older witness releases could leave an OpenCode session whose agent or title is witness-distill when distillation was interrupted. Current releases no longer create or filter those sessions in OpenCode's user database. Before the first import after upgrading, remove any leftover witness-distill sessions with OpenCode's supported session-management tools so they are not captured as normal archive data.

By default the model is downloaded from Hugging Face. A custom WITNESS_MODEL_BASE_URL must serve the same paths (onnx/model.onnx and tokenizer.json) and also set WITNESS_MODEL_SHA256 plus WITNESS_TOKENIZER_SHA256.

Automatic distillation is batched by default: sessions are reconciled on startup and idle, while model work starts at most once every 10 minutes, drains the current queue, then exits so the embed model is not resident. Edit witness config.toml if you want manual-only behavior:

auto_distill = false

If you want to force a different binary, set WITNESS_BIN before starting OpenCode:

export WITNESS_BIN=/absolute/path/to/witness

If you already have your own mcp.witness entry, the plugin leaves it alone. The npm CLI deliberately does not support witness install / witness uninstall; those are source-checkout workflows, not the npm one.