winsmux npm package

This directory is the public npm install surface for winsmux. It covers the CLI package path. The recommended graphical desktop app path is the GitHub Release installer, not this npm package.

For the recommended desktop app, open the latest GitHub Release and download the winsmux_..._x64-setup.exe installer:

• https://github.com/Sora-bluesky/winsmux/releases/latest

The npm package name is winsmux. Repository publishing is tag-driven and uses the staged package from scripts/stage-npm-release.mjs.

The source directory is not the publish artifact. Do not publish packages/winsmux directly from a checkout. The published npm tarball is produced by scripts/stage-npm-release.mjs; install.ps1 is added during staging and pinned to the exact GitHub tag recorded in package metadata.

Install the CLI package on Windows with:

npm install -g winsmux

The winsmux npm command proxies to the bundled Windows installer flow for the CLI package path. It does not install or open the desktop app.

User-facing setup docs:

• https://github.com/Sora-bluesky/winsmux/blob/main/docs/quickstart.md
• https://github.com/Sora-bluesky/winsmux/blob/main/docs/installation.md
• https://github.com/Sora-bluesky/winsmux/blob/main/docs/customization.md

Public contract

• Windows only
• public install command: npm install -g winsmux
• winsmux install
• winsmux update
• winsmux uninstall
• winsmux version
• winsmux help
• the staged package records the exact GitHub release tag in winsmuxReleaseTag; packaging-hotfix tags use a distinct valid npm prerelease version in the reserved pkgfix namespace (for example, v0.36.28.1 becomes npm 0.36.28-pkgfix.1)
• the package source directory is not the publish artifact; the staged package contains the generated release-pinned install.ps1

Installer profiles

The public package will keep one package name and expose profile selection through the installer command instead of publishing separate package names.

| Profile | Shape | Primary use | | ------- | ------- | ------- | | core | runtime binary, wrapper scripts, PATH setup, and base config | users who only need the Windows-native tmux-compatible runtime | | orchestra | core plus orchestration scripts and the Windows Terminal profile | users who need managed pane agents under one operator | | security | core plus vault, redaction, and audit-oriented scripts | users who need credential handling and evidence checks without the full orchestration surface | | full | core, orchestra, and security contents | default public install profile |

The npm form is:

winsmux install --profile full
winsmux update --profile orchestra

install.ps1 accepts the same profile names through -Profile. The package entrypoint forwards --profile to that script as -Profile.

After installation, start the CLI-managed workspace from the project directory that agents should work in:

cd <project>
winsmux init
winsmux launch

winsmux launch is the public CLI startup path for the npm package. It starts the managed Windows Terminal workspace. It does not open the desktop app. For the graphical desktop app, install the desktop app from GitHub Releases and choose the project folder in that app.

Updates keep the previously recorded profile when no new profile is supplied. Each install or update records the selected shape in:

• ~\.winsmux\install-profile
• ~\.winsmux\install-profile.json

Profile scope is enforced by the installer:

• core does not install orchestration scripts, vault support, or the Windows Terminal profile.
• orchestra installs orchestration scripts and the Windows Terminal profile.
• security installs vault-oriented support without the Windows Terminal profile.
• full installs both orchestration and security support.

When a later install or update switches profiles, support scripts that are no longer part of the selected profile are removed from ~\.winsmux\winsmux-core\scripts.

Release gate

• the staged package must pass the Windows verify job
• the publish workflow stays tag-driven
• the publish job uses the staged package from scripts/stage-npm-release.mjs
• the publish job requires the repository NPM_TOKEN secret

License

The public npm package is Apache-2.0. Some runtime compatibility code in the repository keeps an upstream MIT notice. See the repository notices for provenance details:

• https://github.com/Sora-bluesky/winsmux/blob/main/core/LICENSE
• https://github.com/Sora-bluesky/winsmux/blob/main/THIRD_PARTY_NOTICES.md