This plugin targets the opencode 2 (V2) plugin API (Plugin.define, plugins config field, opencode2 CLI). It does not load in opencode V1.
- opencode 2 installed and working (
opencode2) - pandoc for DOCX/XLSX/PPTX writing (PDF and image reading is built in)
# macOS
brew install pandoc
# Debian/Ubuntu
sudo apt-get install pandocAdd the package to the plugins array in opencode 2 configuration:
Per project — opencode.json in the project root:
{
"plugins": ["@sunaookamishirokodev/openoffice-plugin-opencode"]
}Globally — ~/.config/opencode/opencode.json (or the equivalent global config location):
{
"plugins": ["@sunaookamishirokodev/openoffice-plugin-opencode"]
}To pin a version and pass options:
{
"plugins": [
{
"package": "@sunaookamishirokodev/openoffice-plugin-opencode@0.2.1",
"options": {
"pdfEngine": "typst",
"staleLockHours": 48,
"dataDir": "/shared/office-plugin-data"
}
}
]
}opencode installs the package and its dependencies on startup. Then start opencode 2 and try:
Create a Word document at /tmp/test.docx with a table
The agent should call officecli(action="create", ...).
Version matching: this release pins @opencode/plugin@2.0.10 + @opencode/schema@2.0.10 (exact). The plugin loads in opencode 2 GA builds that ship a compatible plugin package. Match your opencode 2 release to the pin, or upgrade the plugin when you upgrade opencode.
Use the published-package flow above when you consume the plugin. When you develop on the plugin itself, see docs/TESTING.md for the full local setup (build, link, configure, verify).
- List active plugin IDs through the V2 API:
opencode2 api get /api/pluginopenoffice should be in the returned list.
- Ask for any document operation (create / read / comment / track change). The agent must call the
officeclitool; theeditoverride must deny binary files with "use officecli for binary files". - If the tool is missing, check the opencode server log (
~/.local/share/opencode/log/opencode.log) for plugin load errors.
| Symptom | Fix |
|---|---|
| Plugin not loading | Confirm the config file is opencode.json (project or global), the field is plugins (V2, not V1's plugin), and the package name is spelled @sunaookamishirokodev/openoffice-plugin-opencode. Check the server log for load errors. |
officecli not available in chat |
Restart opencode 2 after changing config. Check startup logs for load errors. |
| Plugin loads but tools are invisible to the model | Tools are registered with codemode: false for direct provider exposure — verify you are not on a version where the plugin package mismatch prevents registration. |
| pandoc errors on DOCX/XLSX/PPTX | Install pandoc, verify with pandoc --version. |
| Permission errors | The plugin needs write access to its data dir ~/.local/share/opencode/plugins/openoffice/ (or your configured dataDir). |
Releases are automated with Changesets and the Release workflow (.github/workflows/cd.yml):
# 1. Describe each user-facing change (once per change, at PR time or before the release)
bunx changeset
# 2. Push to main — the workflow opens or updates the "Version Packages" PR
# (version bump + CHANGELOG.md). Merge that PR to release.- Merging the Version Packages PR publishes to npm and creates the
v<version>tag plus the GitHub Release (notes taken from the matchingCHANGELOG.mdsection byscripts/release-notes.ts). - The bump type comes from the changesets (minor for features, patch for fixes); do not edit
package.jsonorCHANGELOG.mdby hand. - Publishing uses Trusted Publishing (OIDC) — no npm token secret in CI. CI authenticates via the workflow's
id-token: writepermission and signs with--provenance. - The workflow requires the repository setting Allow GitHub Actions to create and approve pull requests (Settings → Actions → General → Workflow permissions).
npm pins a trusted publisher to an exact workflow filename (case-sensitive). If a publish fails with E404: Not Found - PUT https://registry.npmjs.org/..., the configured workflow and the one that ran no longer match.
Check and update it with npm 11.19+:
npm login --auth-type=web # browser + 2FA
npm whoami # must be the package owner
npm trust list @sunaookamishirokodev/openoffice-plugin-opencodeThe entry must read: repository sunaookamishirokodev/opencode-office-plugin, file cd.yml, permissions publish. To replace it:
npm trust revoke @sunaookamishirokodev/openoffice-plugin-opencode --id=<trust-id>
npm trust github @sunaookamishirokodev/openoffice-plugin-opencode \
--file cd.yml \
--repo sunaookamishirokodev/opencode-office-plugin \
--allow-publish -yOr configure it in the npm web UI — package → Settings → Trusted Publishing → Add trusted publisher → GitHub Actions:
| Field | Value |
|---|---|
| Organization or user | xirothedev |
| Repository | opencode-office-plugin |
| Workflow filename | cd.yml — must match exactly; rename the workflow only after updating this |
| Environment | leave empty |
| Allowed actions | npm publish |
Notes:
- A brand-new scoped package cannot use OIDC for its first publish (npm answers 404 until the package exists with a trusted publisher configured). Publish once locally with
npm login+npm publish --access public(--otp=<code>if 2FA-protected), then add the trusted publisher. - Verify the configuration without cutting a release:
gh workflow run cd.yml. It publishes only whenpackage.jsonholds a version that is not on npm yet. - Trusted publishing only works from GitHub-hosted runners, and the workflow must keep
id-token: write. - The registry read (
npm view) can lag right after a publish (packument CDN). The release workflow handles this by trusting the Changesetspublishedoutput first and retrying the registry check.