Installation

The current repository interface and the latest package in every channel may not be the same. Before following the rest of the documentation, verify that slipway --help lists the seven user commands install, uninstall, list, doctor, run, status, and stop, plus the public protocol machine-interface group used by generated adapters. protocol is a published structured interface, not an eighth user workflow.

For an unreleased checkout, its code, a freshly built binary’s --help, and observable behavior establish the current implementation facts. For a tagged release, use its release notes and the artifacts actually attached to that tag to establish published behavior. Tests, acceptance runs, and CI are verification evidence for a particular revision and execution, not contract authority, a readiness verdict, or proof that an artifact was released.

Build the current checkout

Use the Go version declared in go.mod (currently Go 1.26.5 or newer):

go build -o ./slipway .
./slipway --help

This is the reliable way to evaluate an unreleased repository revision.

Tagged releases

Choose a tag whose release notes include the seven-user-command soft-autopilot interface and public protocol group. Core release artifacts are published on GitHub Releases:

• .tar.gz archives for Linux and macOS;
• .zip archives for Windows;
• .deb, .rpm, and .apk Linux packages;
• checksums.txt and SBOMs;
• versioned images at ghcr.io/signalridge/slipway.

SLSA provenance is generated by an independent post-release job and is attached when that job succeeds. Its absence does not mean that the already-published core archives, packages, checksums, or SBOMs were never created; verify the artifacts that are actually present for the selected tag.

Download the archive and checksums.txt, verify the archive before extracting it, then place slipway (or slipway.exe) on PATH.

Linux packages can be installed from the download directory:

# Debian or Ubuntu
sudo apt install ./slipway*.deb

# Fedora, RHEL, or another RPM-based distribution
sudo dnf install ./slipway*.rpm

# Alpine
sudo apk add --allow-untrusted ./slipway*.apk

Verify the installed interface:

slipway --version
slipway --help

Go installation from a tag

Do not use @latest until the latest release contains this interface. Pin a compatible tag:

go install github.com/signalridge/slipway@vX.Y.Z

A binary built with go install may show development version metadata because release linker flags are not present; use the pinned module version and command tree to establish compatibility.

Container

docker pull ghcr.io/signalridge/slipway:vX.Y.Z
docker run --rm ghcr.io/signalridge/slipway:vX.Y.Z --help

The image includes Git. To install capabilities or create Run data in a mounted Linux worktree, use the host UID/GID:

docker run --rm --user "$(id -u):$(id -g)" \
  -v "$PWD:/workspace" -w /workspace \
  ghcr.io/signalridge/slipway:vX.Y.Z install --tool claude

Nix

Pin the flake to a compatible tag. An unqualified GitHub flake follows the repository’s mutable default branch.

nix run github:signalridge/slipway/vX.Y.Z -- --help
nix profile install github:signalridge/slipway/vX.Y.Z

Optional package-manager channels

Homebrew, Scoop, and AUR are secondary publishers and may lag the core GitHub release. Check the displayed version and run slipway --help after installation.

Homebrew cask

The release workflow tests an explicit tap and trust sequence:

brew tap signalridge/tap
brew trust signalridge/tap
brew install --cask slipway

Scoop

scoop bucket add signalridge https://github.com/signalridge/scoop-bucket
scoop install signalridge/slipway

AUR

yay -S slipway-bin

Install host capabilities

Run from inside the target Git worktree:

The commands below use ./slipway, the binary built from this checkout. If you installed a compatible tagged package, use the slipway binary on PATH instead.

./slipway install --tool claude
./slipway list
./slipway doctor

Supported IDs are claude, codex, copilot, cursor, kilo, kiro, opencode, pi, qwen, and windsurf. Repeat --tool to select several hosts, or pass one comma-separated value such as --tool claude,codex.

Kiro needs an explicit surface on its first install:

./slipway install --tool kiro --surface ide   # or: --surface cli

When Kiro is part of a mixed selection, --surface applies only to Kiro; for example, --tool claude --tool kiro --surface ide and --tool all --surface ide are valid. Refresh and uninstall infer the recorded Kiro surface.

Without --tool, Slipway uses detected host directories. Detection is only a convenience; inspect ./slipway list before installing into a repository with several host configurations.

Refresh and uninstall

./slipway install --tool claude --refresh
./slipway uninstall --tool claude

Slipway records generated paths and hashes in a per-host ownership manifest. Refresh and uninstall mutate only matching managed files. Modified, unknown, malformed, out-of-host, or symlinked paths are preserved or rejected and reported; host settings remain outside adapter ownership.

When a current manifest still claims bytes generated by an earlier release, refresh and uninstall preserve that file and withdraw the stale claim instead of treating it as safe to overwrite or delete. Inspect and move aside the preserved file, then rerun slipway install --refresh if you want the current release to regenerate it.

Do not forge or edit an ownership manifest to recover an installation. If the current manifest is missing but .adapter-generated or generated-looking files remain, first back up and inspect the host surface. Move aside only the sentinel and files you want Slipway to recreate, then rerun slipway install for that host. Files left in place stay preserved and are never adopted. This is manual recovery, not manifest reconstruction or automatic migration.

Removing an adapter does not remove Run journals. See Runs, recovery, and privacy for Run retention.