Skip to content

README.md

Latest commit

 

History

History
146 lines (104 loc) · 4.72 KB

README.md

File metadata and controls

146 lines (104 loc) · 4.72 KB
Raw

Opencode Windows Encoding

npm version License: AGPL v3

OpenCode plugin that fixes UTF-8 encoding issues when executing shell commands on Windows. Zero npm runtime dependencies.

The Problem

When OpenCode runs shell commands on Windows, the console output encoding defaults to the system locale (e.g., GBK for zh-CN). This causes garbled text when LLM-generated commands produce UTF-8 output — breaking file paths, error messages, and all non-ASCII content.

How It Works

This plugin hooks into OpenCode's tool.execute.before event, detects the configured shell from OpenCode's config (config.shell), and injects the matching UTF-8 encoding configuration before every shell command:

PowerShell (pwsh):

[Console]::OutputEncoding=[Console]::InputEncoding=[Text.Encoding]::UTF8;$OutputEncoding=[Text.Encoding]::UTF8;$env:PYTHONIOENCODING='utf-8';

Bash / POSIX shells (bash, zsh, sh, ...):

export LC_ALL=C.UTF-8; export LANG=C.UTF-8; export PYTHONIOENCODING=utf-8;

Command Prompt (cmd):

chcp 65001 >nul

Key behaviors:

  • Shell auto-detection — reads config.shell from OpenCode at startup; falls back to platform detection (pwsh on Windows, bash elsewhere) when unset or unavailable
  • Automatic injection — applies to all bash and shell tool calls
  • Idempotent — skips commands that already contain the shell's encoding marker (OutputEncoding / LC_ALL / chcp) to avoid duplication
  • set prefix aware — preserves PowerShell set VAR="value" prefixes before injecting
  • Zero config — works out of the box with no options
  • Debug logging off by default — set OPENCODE_UTF8_DEBUG=1 to enable diagnostic logging to $TMP/utf8-plugin.log

Installation (OpenCode V1)

npm install opencode-windows-encoding

Usage (OpenCode V1)

Add the plugin to your opencode.jsonc:

{
  "plugin": [
    "opencode-windows-encoding"
  ]
}

Or with a specific version:

{
  "plugin": [
    "opencode-windows-encoding@^1.1"
  ]
}

After adding the plugin, restart OpenCode. All subsequent shell commands will use UTF-8 encoding automatically.

OpenCode V2 (opencode2)

Since v4.1.0 the main line works on both V1 and V2 hosts — no separate dist-tag is needed:

{
  "plugin": [
    "opencode-windows-encoding@latest"
  ]
}

The default export is a combined { id, server, setup } module:

  • V1 hosts (opencode ≤ 1.17, or a local path reference on 1.18.x) call server and inject via tool.execute.before.
  • V2 hosts validate id + setup. The setup registers the shell create.before hook on hosts that expose a shell hook domain (contract verified against the opencode dev branch; the resolved shell is provided directly on event.shell, so no config.shell lookup is needed). On V2 hosts without the shell domain (e.g. opencode 1.18.x) the setup degrades to a no-op — the plugin loads cleanly and activates automatically once the host gains the hook.

Note: the legacy beta dist-tag (opencode-windows-encoding@beta) is deprecated — the main line supersedes it.

Local Usage (Copy & Go)

The built V1 plugin is a single self-contained JavaScript file (the shared core is bundled inline). From a clone of this repo:

npm install && npm run build

Then copy dist/v1.js to OpenCode's plugins directory with a .ts extension (opencode 1.18.x auto-discovery resolves .js files unreliably on Windows; the bundled output is plain ESM JavaScript, which loads fine as .ts):

PowerShell:

Copy-Item dist/v1.js $env:USERPROFILE/.config/opencode/plugins/utf8-encoding.ts

Bash / WSL:

cp dist/v1.js ~/.config/opencode/plugins/utf8-encoding.ts

Restart OpenCode to apply.

The built file uses only Node.js built-ins (node:fs, node:os, node:path) and a compile-time-only import type from @opencode-ai/plugin — zero npm runtime dependencies.

Requirements

  • OpenCode (any recent version with plugin support)
  • Windows (this plugin is designed specifically for Windows encoding issues)
  • Any of: PowerShell 7+ (pwsh), Bash, or Command Prompt (cmd)

Development

# Install dependencies
npm install

# Build
npm run build

# Type check
npm run typecheck

# Watch mode (for development)
npm run dev

Local Development Testing

Reference the source file directly:

{
  "plugin": [
    "/path/to/opencode-windows-encoding/src/v1.ts"
  ]
}

License

AGPL-3.0 — see LICENSE for details.