Windows Support

Jcode supports Windows as a first-class platform. The Windows implementation uses native named pipes, Windows process management, PowerShell installation, and platform-specific launch-hotkey integration.

Support status

Area	Status
Windows 11 x64	Supported and manually verified
Windows 11 ARM64	Release builds and automated install checks
PowerShell installer	Tested on Windows CI
Native IPC and process lifecycle	Covered by targeted and end-to-end Windows tests
jcode update	Supported with SHA-256 verification
Release assets	x64 and ARM64 .exe and .tar.gz assets
Authenticode signing	Release pipeline ready; requires the one-time Azure configuration below

PowerShell 5.1 or later is required by the installer. The x64 build is the default for Intel and AMD Windows computers. The ARM64 build is selected automatically on ARM64 Windows.

Install

Open PowerShell and run:

irm https://jcode.sh/install.ps1 | iex

The installer:

1. Detects x64 or ARM64.
2. Downloads the matching asset from the official GitHub release.
3. Verifies it against the release's SHA256SUMS file.
4. Installs immutable, stable, and launcher copies under %LOCALAPPDATA%\jcode.
5. Adds %LOCALAPPDATA%\jcode\bin to the user PATH.

Alacritty installation and the global launch hotkey are optional and are no longer installed automatically. To request both explicitly:

$script = [scriptblock]::Create((irm https://jcode.sh/install.ps1))
& $script -ConfigureAlacritty -ConfigureHotkey

Jcode can also offer these options interactively after launch.

If a release does not contain a matching prebuilt Windows asset, the installer fails with an actionable message rather than silently starting a long build. To explicitly allow a source build:

$script = [scriptblock]::Create((irm https://jcode.sh/install.ps1))
& $script -BuildFromSource

Source builds require Git, Rust, and Visual Studio 2022 Build Tools with the Desktop development with C++ workload.

Install paths

• Launcher: %LOCALAPPDATA%\jcode\bin\jcode.exe
• Stable binary: %LOCALAPPDATA%\jcode\builds\stable\jcode.exe
• Versioned binary: %LOCALAPPDATA%\jcode\builds\versions\<version>\jcode.exe
• User data and configuration: %USERPROFILE%\.jcode

Verify an installation

jcode --version
Get-Command jcode
Get-FileHash (Get-Command jcode).Source -Algorithm SHA256

Compare the hash with SHA256SUMS on the matching GitHub release.

After Authenticode signing is enabled, this must report Valid:

Get-AuthenticodeSignature (Get-Command jcode).Source | Format-List Status,StatusMessage,SignerCertificate

Microsoft Defender and SmartScreen

Two different Windows warnings are commonly confused:

• Microsoft Defender SmartScreen shows messages such as “Windows protected your PC” when a downloaded application is unsigned or has not accumulated enough publisher reputation. Authenticode signing with a trusted, timestamped certificate is the primary fix. Reputation still builds over time for a new publisher identity.
• Microsoft Defender Antivirus reports a named threat or suspicious behavior. Signing helps establish provenance, but a heuristic false positive must also be submitted to Microsoft with the exact signed file and SHA-256 hash.

Do not tell users to disable Defender, add exclusions, or bypass a named malware detection. First verify the release URL, checksum, and Authenticode signature. If a correctly signed official build is still detected, submit it through the Microsoft Security Intelligence file submission portal as a software developer false positive.

Heuristic-trigger reduction already in place

The Windows setup is deliberately designed to avoid unnecessary suspicious behavior:

• Release downloads are verified against SHA256SUMS.
• Optional terminal and global-hotkey setup requires explicit consent.
• The old hidden VBScript startup trampoline has been removed.
• The hotkey listener uses a direct PowerShell shortcut with RemoteSigned, not ExecutionPolicy Bypass.
• Release binaries are built on GitHub-hosted Windows runners and tested before publication.

Enable Authenticode signing

The release workflow supports Azure Artifact Signing with GitHub OIDC. This keeps the certificate private key in Microsoft's managed signing service instead of exporting it into a GitHub secret.

This is a one-time owner setup and may require Azure billing and organization or identity verification:

1. Create an Artifact Signing account and a public-trust certificate profile.
2. Create a Microsoft Entra application or managed identity with a federated credential for 1jehuang/jcode GitHub Actions.
3. Grant it the Artifact Signing Certificate Profile Signer role on the certificate profile.
4. Add these GitHub Actions secrets:
   • AZURE_CLIENT_ID
   • AZURE_TENANT_ID
   • AZURE_SUBSCRIPTION_ID
5. Add these GitHub Actions variables:
   • WINDOWS_SIGNING_ENDPOINT, for example https://eus.codesigning.azure.net/
   • WINDOWS_SIGNING_ACCOUNT
   • WINDOWS_SIGNING_CERTIFICATE_PROFILE
6. Push a test tag and confirm the Sign and publish Windows assets job signs both executables and that Get-AuthenticodeSignature returns Valid.
7. Leave WINDOWS_SIGNING_REQUIRED unset or set it to true. Signing is required by default for Windows assets, so missing configuration or a signing outage omits Windows from that release while every other successful platform can still publish. Setting it to false is an explicit emergency override and is not suitable for an official Windows release.

The workflow applies SHA-256 Authenticode signatures and RFC 3161 timestamps before packaging, checksum generation, and release upload. Both x64 and ARM64 executables are signed on a supported x64 Windows signing runner.

Do not describe the Defender and SmartScreen rollout as complete until signing enforcement is active and a public release has a valid signature.

Release acceptance checklist

For every release that changes Windows behavior:

• Windows x64 CI build and targeted tests pass.
• Windows lifecycle end-to-end tests pass.
• x64 and ARM64 installer verification passes.
• Both .exe files have a valid, timestamped Authenticode signature.
• SHA256SUMS contains both Windows executables and archives.
• A clean Windows 11 machine installs, launches, updates, and uninstalls successfully.
• Defender Antivirus reports no named detection on the signed release.
• SmartScreen identifies the expected publisher. Any low-reputation warning is tracked separately from malware detection.
• The website Windows button points to a published asset and contains no preview or work-in-progress wording.
• Release notes mention material Windows fixes or limitations.

Continuous integration

Windows is covered by:

• .github/workflows/ci.yml: release build, test compilation, targeted platform tests, runtime smoke tests, lifecycle end-to-end tests, installer verification, and PowerShell syntax checks.
• .github/workflows/windows-smoke.yml: manually dispatchable x64 and ARM64 smoke validation.
• .github/workflows/release.yml: x64 and ARM64 builds, managed signing required for Windows publication, signature verification, packaging, and checksums. Every platform and architecture publishes independently, so a Windows failure cannot block any successful Unix asset.

Architecture notes

Unix domain sockets are replaced by Windows named pipes under crates/jcode-base/src/transport/windows.rs. Platform-specific filesystem, process, update, and replacement behavior is selected at compile time with #[cfg(windows)], so Windows support does not add runtime branching to Unix builds.

Windows launch-hotkey setup is implemented in crates/jcode-setup-hints/src/windows_setup.rs and is only installed after explicit user consent.

Reporting Windows problems

Include the following in a GitHub issue:

• Windows edition, version, and architecture
• Jcode version from jcode --version
• Installation method
• Terminal and PowerShell version ($PSVersionTable.PSVersion)
• Exact Defender or SmartScreen message
• Defender threat name, if one was shown
• SHA-256 from Get-FileHash
• Authenticode status from Get-AuthenticodeSignature

Do not upload private configuration, credentials, session transcripts, or .jcode authentication files.