Windows notes

Windows 10 1809+ / Windows 11 is a best-effort compatibility target. Linux is the primary development and required CI platform; native Windows CI and smoke testing do not automatically gate PRs or releases. Windows packaging, runtime abstractions and useful regression tests remain, and reproducible Windows bugs should be fixed when practical. The full Ubuntu suite retains deterministic Windows path/process/platform coverage.

Reference for running and developing Clanker Grid on Windows.

Best-effort supported: Windows 10 1809+ and Windows 11, x64. Not supported: ARM64, WSL (use the Linux AppImage instead).

Installing a release build

Windows artifacts are produced only for releases that explicitly include a Windows build. Linux-only releases ship only the AppImage.

When a Windows build is produced, it includes:

Both are unsigned in the current release. On first launch, Windows SmartScreen displays:

Windows protected your PC. Microsoft Defender SmartScreen prevented an unrecognized app from starting.

Choose More info → Run anyway to continue. Code signing is planned for a follow-up release.

App data location

App settings and persisted state live under:

%APPDATA%\Clanker Grid\

This resolves via Electron's app.getPath('userData') and is preserved across upgrades. Uninstalling the NSIS build does not by default clear this directory.

Git for Windows

Install Git for Windows for any local development. The husky pre-commit hook (.husky/pre-commit) runs through the sh bundled with Git for Windows; without it, commits skip the hook silently.

After install, confirm:

git --version
sh --version

Recommended Git settings

git config --global core.autocrlf input

Keeps the working tree LF-on-disk while still letting Windows tooling render CRLF where it expects it. Clanker Grid's editor preserves whatever line ending a file already has on save (CRLF stays CRLF, LF stays LF), so core.autocrlf=input avoids accidental rewrites in mixed-platform repos.

Long path support

Some toolchains and nested dependency trees can exceed the legacy 260-character Windows path limit. Enable long paths via either:

• Group Policy: Computer Configuration → Administrative Templates → System → Filesystem → Enable Win32 long paths.
• Registry: set HKLM\SYSTEM\CurrentControlSet\Control\FileSystem\LongPathsEnabled to 1.

Restart the machine after enabling.

UNC workspaces and file watching

Clanker Grid accepts UNC-style workspace paths (\\server\share\project) and Windows drive-letter paths (C:\projects\foo) in Open Workspace. Backslashes are normalized to forward slashes at the IPC boundary; you do not need to convert them by hand.

For UNC paths, the explorer file watcher automatically falls back to polling because native fs.watch events are unreliable across SMB. To force polling on any workspace (for example when debugging watcher issues on a local path):

set CLANKER_GRID_WATCHER_POLLING=1

Or, for PowerShell:

$env:CLANKER_GRID_WATCHER_POLLING = "1"

SSH home / .ssh lookup

The Windows desktop app can use system OpenSSH to connect to supported Linux/POSIX SSH workspaces. The remote host itself must not be Windows in V1. See SSH Workspaces.

Credential code resolves the SSH parent directory in this order on Windows:

1. %USERPROFILE%\.ssh (preferred — matches the OpenSSH default)
2. $HOME\.ssh (fallback — only if %USERPROFILE% is unavailable)
3. os.homedir()\.ssh (final fallback)

This avoids common toolchain cases (Git Bash, MSYS) that set HOME to a non-user-profile location.

SSH key permissions

POSIX file modes (mode 0600, chmod) are no-ops on Windows NTFS. Clanker Grid relies on inherited NTFS ACLs under %USERPROFILE%\.ssh: as long as the parent .ssh directory has the standard "current-user-only" ACLs that OpenSSH for Windows applies, generated keys inherit safe permissions automatically.

If you have customized .ssh ACLs and need to lock them down, run icacls manually after key generation — Clanker Grid does not modify ACLs on Windows.

Default shell

PowerShell (powershell.exe) is the default session shell on Windows. Clanker Grid does not pass -i (a bash-only flag) on Windows; PowerShell launches in interactive mode by default.

The Windows default shell is fixed to powershell.exe; the SHELL environment variable applies only on Linux/macOS.

Harness launch on Windows

npm-installed CLI tools (Codex, Claude, OpenCode, Pi) are installed as .cmd shim scripts on Windows. Clanker Grid resolves the command through PATH/PATHEXT itself (resolveHarnessPtySpawn(), sharing planBoundedSpawn() with bounded command execution). Real executables (.exe) launch directly with no shell; .cmd/.bat shims run through cmd.exe /d /s /c with escaped arguments. Arguments a shim cannot carry safely (%, CR/LF) and unresolvable commands fail the launch with a typed error instead of reaching cmd /c. No manual configuration is required.

This applies to every local harness PTY: toolbar launches, workspace-launcher launches and resumed or forked conversations. A resumed session builds its final arguments (including any agent-attention additions) and its final child environment first, and only then resolves the command, so the planner sees exactly what will run. Unsafe or unresolvable commands fail closed with a typed error. Automated tests use injected Windows platform and file-lookup seams to cover .exe, .cmd/.bat escaping, PATH/PATHEXT/ComSpec resolution and rejection paths; they are not a substitute for a real Windows host.

Hermes Assistants (service detection, profile roster, Bot Chat, Browser sidecar) are written to be platform-safe, but no live Windows Hermes Assistants or UI smoke test has been performed, and the current release artifact is Linux-only. Treat any Windows regression there as a bug.

The POSIX wrapper script that Clanker Grid generates on Linux/macOS (~/.clanker-grid/harness-wrapper.sh) is not generated on Windows — harnesses run directly.

File watcher implementation

The editor's file watcher uses raw fs.watch (not chokidar) with rewatch-on-rename so atomic-save flows on Windows survive temp→target renames without flapping. The explorer watcher uses chokidar with platform-tuned awaitWriteFinish and an unlink+add collapse window so atomic saves do not produce visible flicker.

These are implementation details, not user-facing settings — they are documented here so contributors auditing watcher behavior on Windows know what is intentional.

Reporting Windows-only issues

When filing a Windows-specific bug, please include:

• Windows edition and build (winver).
• PowerShell version ($PSVersionTable).
• Whether the workspace path is local, drive-letter, or UNC.
• Whether long-path support is enabled.
• DevTools console output if the issue affects the renderer.