Plan: OpenCode Windows And WSL Support

• Status: Planned for a later cross-platform implementation pass
• Date: 2026-05-28
• Task: COL-133
• Related ADR: OpenCode Support Integration Contract

Purpose

Define how Coldtea should support OpenCode on Windows before implementation starts. This document is a planning contract, not an implementation change.

The goal is to preserve Coldtea's transparent terminal-host model while avoiding silent assumptions that only work on macOS or Linux.

Sources Checked

• OpenCode intro/install docs: https://opencode.ai/docs/
• OpenCode Windows/WSL docs: https://opencode.ai/docs/windows-wsl
• OpenCode config docs: https://opencode.ai/docs/config/
• OpenCode CLI docs: https://opencode.ai/docs/cli/
• OpenCode troubleshooting docs: https://opencode.ai/docs/troubleshooting/
• Current Coldtea OpenCode ADR and QA runbook.
• Current Coldtea OpenCode code paths in apps/desktop/src-tauri/src/agents/, apps/desktop/src-tauri/src/agent_enablement.rs, apps/desktop/src-tauri/src/agent_setup/, and terminal.rs.

Assumptions

• Coldtea remains PTY/TUI-first for OpenCode. Windows support must not replace the visible OpenCode TUI with SDK/server/ACP control.
• OpenCode's own docs recommend WSL for the best Windows experience, while native Windows installs are available through Chocolatey, Scoop, npm, Mise, Docker, or a release binary.
• Coldtea's first Windows implementation should optimize for one reliable path rather than trying PowerShell, cmd, Git Bash, native Node shims, and WSL at once.

First-Pass Support Decision

First-pass Windows support for OpenCode should be WSL-only.

In scope:

• Detect WSL availability on native Windows.
• Detect opencode inside a selected WSL distro.
• Launch OpenCode inside that WSL distro in a real Coldtea PTY.
• Support projects stored in the WSL filesystem for the initial WSL release.
• Defer Windows drive projects mounted under /mnt/<drive>/ until path conversion, read/write behavior, git behavior, and session metadata access are verified in a separate promotion step.
• Keep all OpenCode config, auth, plugins, sessions, and logs in the same WSL distro that runs opencode.
• Show clear UI/docs messaging when WSL or WSL OpenCode is missing.

Out of scope for the first pass:

• Native Windows OpenCode launch through PowerShell.
• Native Windows OpenCode launch through cmd.exe.
• Git Bash as a compatibility layer for native Windows OpenCode.
• Running or managing opencode serve, opencode web, SDK, or ACP as the default Windows path.
• Reading or mutating OpenCode provider credentials on any platform.

Native Windows OpenCode can be evaluated later, after the WSL path is stable and manual QA proves OpenCode behaves consistently under ConPTY and Windows package manager shims.

User-Facing Behavior

On native Windows, the OpenCode launcher should report one of these states:

The UI must not silently offer a native Windows opencode binary as launchable while the implementation only supports WSL. Native binaries should either be ignored for OpenCode launch health or surfaced as an unsupported diagnostic.

Platform-Specific OpenCode Paths

opencode db path is the source of truth for the database whenever possible. The paths below are fallback locations and documentation references, not a reason to bypass OpenCode's CLI when the CLI is available.

macOS, Linux, And WSL

These paths apply inside the environment where opencode runs. For WSL, that means inside the selected distro, not in the Windows user profile.

Coldtea's WSL-managed wrapper/plugin files should also live inside the selected WSL distro so OpenCode can read them without Windows path translation.

Native Windows

Native Windows paths are documented here for future support and guardrails. They are not first-pass launch targets.

Coldtea must treat these as OpenCode-owned locations. It can resolve them for health checks, docs, or read-only session metadata, but it must not write provider credentials or broad user config there.

Shell Behavior Contract

Unix Shells

macOS/Linux behavior remains unchanged:

• Launch through the user's shell with Coldtea's existing shell integration.
• Prefer zsh/bash wrapper paths when available.
• Preserve user OPENCODE_CONFIG, OPENCODE_TUI_CONFIG, OPENCODE_CONFIG_DIR, and OPENCODE_CONFIG_CONTENT values.
• Use Coldtea-managed OPENCODE_CONFIG_DIR and session-scoped OPENCODE_CONFIG_CONTENT only when doing so does not clobber user values.

WSL Shells

WSL launch should be an explicit runtime, not an accidental fallback through the Windows process PATH.

Expected behavior:

• Detect distros with wsl.exe --list --quiet or equivalent Windows API.
• Resolve opencode by running a command inside the selected distro, for example a login-compatible sh/bash command that executes command -v opencode.
• Launch through wsl.exe into the selected distro and run OpenCode inside a Linux shell. Do not launch a Windows shim that happens to call WSL.
• Install or expose Coldtea's OpenCode plugin/wrapper files inside the WSL filesystem.
• Resolve opencode db path inside the same distro before reading session metadata.
• Translate paths only at process boundaries:
  • Windows host path to WSL path for cwd when launching.
  • WSL path to a Windows-readable UNC path only if the native Windows process must read a file directly.

If path translation fails, the launcher should fail actionably instead of falling back to a different shell or project directory.

Windows Drive Projects Under WSL

Projects mounted from Windows drives, such as /mnt/c/..., are deferred for the initial WSL release. The first supported WSL milestone should require projects to live in the WSL filesystem, for example under ~/code/.

Promote /mnt/<drive>/ projects only after QA verifies all of the following in the same WSL distro:

• Windows host path to WSL cwd conversion.
• File read/write behavior through OpenCode tools.
• Git status, branch, and worktree behavior.
• Coldtea file watching and editor path handling.
• opencode db path, session list, resume, fork, and delete behavior.
• Failure copy when a Windows path cannot be converted or accessed from WSL.

PowerShell

PowerShell is out of scope for first-pass OpenCode launch.

Future native support must not reuse POSIX wrapper scripts. It should use either PowerShell-native wrapper logic or direct process launch with explicit environment variables. Quoting, .ps1 execution policy, opencode.cmd shims, and provider environment inheritance need separate tests.

cmd.exe

cmd.exe is out of scope for first-pass OpenCode launch.

Future native support needs dedicated handling for .cmd/.bat shims, PATHEXT, percent-style environment expansion, and argument quoting. It should not inherit Unix shell assumptions like exec, command -v, $HOME, or single-quote shell escaping.

Git Bash

Git Bash is out of scope for first-pass OpenCode launch.

OpenCode exposes OPENCODE_GIT_BASH_PATH for Windows shell configuration, but Coldtea should not treat Git Bash as equivalent to WSL. If Git Bash support is added later, it should be a native Windows mode with its own QA matrix and clear copy.

Implementation Guardrails

Before Windows/WSL implementation starts, introduce a runtime boundary so agent code does not scatter platform checks across unrelated modules.

Recommended shape:

• Add an AgentRuntime or equivalent abstraction for:
  • detection command execution;
  • launch command construction;
  • shell integration paths;
  • OpenCode DB path resolution;
  • host/distro path translation;
  • delete/session commands.
• Model at least these runtimes:
  • UnixHost for current macOS/Linux behavior;
  • WindowsWsl for first-pass Windows support;
  • WindowsNativeUnsupported for clear messaging;
  • a future WindowsNative only after native support is approved.
• Keep OpenCode-specific path fallbacks behind platform-aware helpers.
• Do not call /bin/zsh, /bin/bash, /bin/sh, command -v, or POSIX shell quoting helpers from native Windows code paths.
• Do not call Windows where, PowerShell, or cmd.exe from WSL runtime logic.
• Do not assume HOME, XDG_CONFIG_HOME, or .local/share identify the correct OpenCode profile when a native Windows process is managing a WSL OpenCode process.
• Do not read a WSL SQLite database through a Windows path until path conversion and file-locking behavior have been manually verified. If unsafe, return an empty session list with an actionable diagnostic rather than blocking launch.
• Keep native Windows OpenCode detection separate from launch availability so unsupported binaries do not appear as ready.

QA Requirements

Add Windows/WSL scenarios to the OpenCode QA runbook before implementation is accepted:

1. Native Windows with no WSL installed shows WSL-required messaging.
2. WSL installed but no distro configured shows setup-required messaging.
3. WSL distro installed but opencode missing shows install-in-WSL messaging.
4. Native Windows opencode installed, WSL opencode missing, stays unsupported for launch.
5. WSL opencode installed in a distro launches the native TUI in a Coldtea PTY.
6. A project under the WSL home filesystem launches with the correct Linux cwd.
7. A project under /mnt/c/... remains unsupported until the Windows-drive promotion checks above pass.
8. Coldtea MCP/startup prompt and OpenCode plugin events work from WSL without writing tokens into durable OpenCode config.
9. opencode db path, session listing, resume, fork, and delete operate inside the same WSL distro or fail safely with clear messaging.
10. macOS/Linux OpenCode behavior remains unchanged.

Native PowerShell, cmd, and Git Bash tests belong to a later native-Windows support task, not the WSL first pass.

Open Questions For Implementation

• How will users choose or remember a WSL distro when more than one is installed?
• Which release should promote Windows drive workspaces after the /mnt/<drive>/ path-conversion, file, git, watcher, and session-metadata checks pass?
• Should session metadata read the WSL SQLite DB through \\wsl$\..., or should Coldtea use a WSL-side helper/CLI command to avoid host file-locking issues?
• Where should WSL-specific shell integration files be installed and versioned when the native Windows app manages multiple distros?
• What is the smallest supported Windows version/build for ConPTY + WSL launch?

Acceptance Checklist

A future implementation can claim COL-133's plan is satisfied when:

• First-pass Windows support is explicitly WSL-only.
• The initial WSL project scope is explicitly WSL-filesystem-only, with /mnt/<drive>/ projects deferred until promotion checks pass.
• Native Windows OpenCode is documented as unsupported for the first pass.
• Platform-specific OpenCode config/auth/plugin/DB paths are documented.
• Shell behavior for Unix, WSL, PowerShell, cmd, and Git Bash is explicit.
• Unsupported states have clear product copy.
• Follow-up implementation work has concrete platform guards and QA scenarios.