How To Install And Refresh Adapters

Use this guide when you need a working Slipway binary and generated AI-tool surfaces for the current repository.

For the complete release matrix, checksums, container image, package-manager channels, and source-build details, see Installation.

Install The CLI

Use a release-backed channel when possible:

Platform	Recommended path
macOS	`brew install --cask signalridge/tap/slipway`
Windows	`scoop bucket add signalridge https://github.com/signalridge/scoop-bucket` `scoop install slipway`
Linux	Use the `.deb`, `.rpm`, `.apk`, `tar.gz`, AUR, or container image paths in Installation.

Use Go install when release packages are unavailable or you intentionally want a Go-managed binary:

go install github.com/signalridge/slipway@latest

Verify the install:

slipway --help

If an AI tool finds a same-name package in an unrecognized registry, stop and verify ownership before installing it.

Initialize Slipway In A Repo

From the repository root:

slipway init --tools codex

Common adapter choices:

slipway init --tools claude
slipway init --tools claude,codex,opencode
slipway init --tools all
slipway init --tools none

--tools none initializes the runtime layout and .slipway.yaml without writing host adapter files.

Inspect the diff before committing generated files:

git status --short
git diff -- .slipway.yaml .claude .codex .cursor .opencode .pi

Commit .slipway.yaml when the repo should share Slipway defaults. Commit generated adapter files only according to the repository’s policy.

Refresh Existing Adapters

Refresh auto-detected Slipway-managed adapters:

slipway init --refresh

Refresh a specific set:

slipway init --tools codex,opencode --refresh

Refresh every supported adapter:

slipway init --tools all --refresh

Refresh detects Slipway generated markers. It does not treat a bare .claude, .codex, .cursor, .opencode, or .pi directory as owned by Slipway.

Preserve User-Owned Files

Before accepting a refresh diff, check adjacent host config:

git status --short .claude .codex .cursor .opencode .pi

Generated files route to the CLI. User-owned host settings, local prompts, manual commands, and non-Slipway hooks should stay intact.

If refresh output removes a legacy Slipway-owned launcher or prompt, verify that the new generated surface exists before committing. Codex command surfaces now live under:

.codex/skills/slipway-<command>/SKILL.md

Pi’s session-start bridge is generated as:

.pi/extensions/slipway-hooks.ts

After Changing Command Or Skill Surfaces

If you changed command registrations, generated skills, JSON contracts, or docs tokens, update the surface manifest:

go run ./internal/toolgen/cmd/gen-surface-manifest --write
go test ./internal/toolgen -run SurfaceManifest -count=1

The manifest is derived from Go authorities and documentation tokens. Do not hand-edit generated rows unless you are repairing the generator itself.