Install

Install Kusaw on macOS, Linux, or Windows. On Windows, use PowerShell or Windows Terminal, with Git for Windows installed.

RequirementsCopy Anchor Link

• git on PATH. On Windows, Git for Windows provides git and sh, which Kusaw uses to run verification commands.
• Claude Code installed and signed in. Kusaw does not copy those steps and does not ask for credentials or a model. A real run starts your configured Claude Code, which uses your account and plan.
• Cursor is optional and stays off until you enable it. Provider setup is in Providers.

Build from sourceCopy Anchor Link

Building from source is the main way to install. You need Go 1.27, plus Node.js 24 LTS and npm if you want the Dashboard built into the binary.

git clone https://github.com/cloud101co/kusaw.git
cd kusaw
make build

The binary is bin/kusaw (bin/kusaw.exe on Windows).

Without Node, make build-go (or go build ./cmd/kusaw) still produces a working binary. Until the UI is built, the Dashboard is a placeholder page that tells you to run make web, then make build.

Put kusaw on PATHCopy Anchor Link

make install builds the binary and installs it into /usr/local/bin. It also adds the ksw alias (a symlink, or ksw.cmd on Windows) and shell completions for both names:

make install                      # may need sudo for /usr/local/bin
make install PREFIX=$HOME/.local  # installs into ~/.local/bin

make install rebuilds only the Go binary. It embeds the Dashboard only if make build (or make web) already built it, so run make build first.

If another program named ksw is already on PATH, the installer leaves it alone and prints a warning. make uninstall (with the same PREFIX) removes the binary and the alias it added.

You can also copy bin/kusaw onto PATH yourself. Then check it:

kusaw version

That prints the version, commit, and build date. ksw is a short alias for the same binary, so every kusaw command in these docs also works as ksw once the alias is installed.

Install a prebuilt releaseCopy Anchor Link

macOS and Linux:

curl -fsSL https://kusaw.com/install.sh | sh

Windows (PowerShell):

irm https://kusaw.com/install.ps1 | iex

Both scripts download the latest release for your OS and CPU, check it against SHA256SUMS, and install kusaw into ~/.local/bin (Windows: %LOCALAPPDATA%\Programs\kusaw). Set KUSAW_INSTALL_DIR to choose another folder. They do not change your PATH; they tell you if the folder is missing from it.

To download by hand, use https://kusaw.com/download/latest/<file> for the newest release or https://kusaw.com/download/<version>/<file> for a specific one. Files are named kusaw_<version>_<os>_<arch>.tar.gz (.zip on Windows); the latest release also has kusaw_<os>_<arch> copies without the version.

Verify your downloadCopy Anchor Link

Download SHA256SUMS from the same folder and check the archive before you run it:

shasum -a 256 -c SHA256SUMS --ignore-missing
# Linux: sha256sum -c SHA256SUMS --ignore-missing

SHA256SUMS.sig signs that file with the Kusaw release key. kusaw update checks both the signature and the checksum before it installs anything; kusaw update --show-key prints the fingerprint of the key built into your binary.

Some managed Macs block unsigned binaries downloaded from the internet. If that happens, build from source.

Where Kusaw keeps its filesCopy Anchor Link

Kusaw keeps the factory registry, instance files, and service logs under <user config dir>/kusaw/. That is ~/.config/kusaw/ on Linux, ~/Library/Application Support/kusaw/ on macOS, and %AppData%\kusaw\ on Windows. Set KUSAW_HOME to use a different folder.

Each factory keeps its own runs, worktrees, and database in its data directory, which is .kusaw next to kusaw.yaml by default.

NextCopy Anchor Link

Your first run.