Install

asz runs on macOS, Linux and Windows, on x86-64 and ARM 64. To record which files each tool call changed, also install the Claude Code plugin.

Install script

Use a version from the downloads page.

On macOS or Linux:

VERSION=<version>
curl -fsSL "https://raw.githubusercontent.com/apache/skywalking-ai-sessionizer/v$VERSION/install/asz.sh" | sh -s -- "$VERSION"

On Windows, in PowerShell:

$Version = "<version>"
& ([scriptblock]::Create((Invoke-RestMethod -UseBasicParsing "https://raw.githubusercontent.com/apache/skywalking-ai-sessionizer/v$Version/install/asz.ps1"))) $Version

The script checks the package’s sha512 and puts asz and asz-changes in ~/.local/bin, or %USERPROFILE%\.local\bin on Windows, which it adds to your Path. Run it again with another version to upgrade. On Windows, stop asz and Claude Code first.

Homebrew, on macOS and Linux

brew trust https://github.com/apache/skywalking-ai-sessionizer
brew tap apache/skywalking-ai-sessionizer https://github.com/apache/skywalking-ai-sessionizer
brew install apache/skywalking-ai-sessionizer/asz

Homebrew 7 loads a tap that is not one of its own only after brew trust. Trust it by the same URL you tap: for this tap, the name apache/skywalking-ai-sessionizer does not match, because the repository is not named homebrew-skywalking-ai-sessionizer. Without it, brew tap stops with Refusing to load formula ... from untrusted tap.

asz installs two programs: asz itself and asz-changes, which records what a tool call changed on disk. To wire a runtime to it, see Claude Code Plugin or LangChain Plugin. Upgrade with brew upgrade asz.

Until 0.5.0 there were two formulae fetching the identical archive and installing one binary each. asz-claude-code is gone. Coming from 0.4.0, follow Upgrading from 0.4.0: brew uninstall asz-claude-code is its last step, after the Claude Code plugin has been reinstalled, because until then the plugin’s hooks still call the binary that formula holds.

For an exact version, install apache/skywalking-ai-sessionizer/asz@<version>. Homebrew keeps it off your PATH; brew info shows where it is.

apt, on Debian and Ubuntu

curl -fsSL https://downloads.apache.org/skywalking/KEYS | gpg --dearmor | sudo tee /usr/share/keyrings/apache-skywalking.gpg > /dev/null
echo "deb [signed-by=/usr/share/keyrings/apache-skywalking.gpg] https://skywalking.apache.org/apt stable main" | sudo tee /etc/apt/sources.list.d/apache-skywalking.list
sudo apt update
sudo apt install asz asz-changes

asz-changes records what a tool call changed on disk; install it on a machine where an agent runs. asz is the collector and the page, and a machine that only receives needs it alone. To wire a runtime to the recorder, see Claude Code Plugin or LangChain Plugin.

Upgrade with sudo apt update && sudo apt upgrade. For an exact version, run sudo apt install asz=<version> asz-changes=<version>.

asz-changes was called asz-claude-code until 0.5.0, and the binary in it was called asz-claude-plugin. Neither name is published any more, so a machine that has the old package keeps it until sudo apt remove asz-claude-code, and the Claude Code plugin has to be reinstalled once so its hooks call the new name. install/claude-code-plugin.sh does that and carries the plugin’s data across.

Binary package

The downloads page links one package per platform:

apache-skywalking-ai-sessionizer-<version>-bin-<os>-<arch>.tgz    os: darwin, linux; arch: amd64, arm64
apache-skywalking-ai-sessionizer-<version>-bin-windows-<arch>.zip  arch: amd64, arm64

Each holds asz, asz-changes (the change recorder), LICENSE, NOTICE and licenses/.

For Debian and Ubuntu, the release directory holds two .deb packages per architecture, one for each program, which sudo apt install ./<file>.deb installs. They are what the apt repository above serves; the downloads page lists the archives only.

apache-skywalking-ai-sessionizer-<version>-bin-asz-<arch>.deb          arch: amd64, arm64
apache-skywalking-ai-sessionizer-<version>-bin-asz-changes-<arch>.deb  arch: amd64, arm64

On macOS or Linux:

OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m | sed -e 's/x86_64/amd64/' -e 's/aarch64/arm64/')
PKG=apache-skywalking-ai-sessionizer-$VERSION-bin-$OS-$ARCH.tgz
curl -fL -o "$PKG" "https://www.apache.org/dyn/closer.lua?path=skywalking/ai-sessionizer/$VERSION/$PKG&action=download"
curl -fLO "https://downloads.apache.org/skywalking/ai-sessionizer/$VERSION/$PKG.sha512"
curl -fLO "https://downloads.apache.org/skywalking/ai-sessionizer/$VERSION/$PKG.asc"

Verify it, then unpack it and put asz on your PATH:

mkdir asz && tar -xzf "$PKG" -C asz
./asz/asz version

If macOS refuses to start a binary a browser downloaded, run xattr -dr com.apple.quarantine asz.

On Windows, in PowerShell:

$Pkg = "apache-skywalking-ai-sessionizer-$Version-bin-windows-amd64.zip"
Invoke-WebRequest -OutFile $Pkg "https://www.apache.org/dyn/closer.lua?path=skywalking/ai-sessionizer/$Version/$Pkg&action=download"
Invoke-WebRequest -OutFile "$Pkg.sha512" "https://downloads.apache.org/skywalking/ai-sessionizer/$Version/$Pkg.sha512"
Invoke-WebRequest -OutFile "$Pkg.asc" "https://downloads.apache.org/skywalking/ai-sessionizer/$Version/$Pkg.asc"
Expand-Archive $Pkg -DestinationPath asz
.\asz\asz.exe version

A version that is no longer on downloads.apache.org is under https://archive.apache.org/dist/skywalking/ai-sessionizer/. Each GitHub release carries the same files.

Verify a package

Take the .sha512, the .asc and KEYS from downloads.apache.org, not from a mirror.

shasum -a 512 -c "$PKG.sha512"
curl -fLO https://downloads.apache.org/skywalking/KEYS
gpg --import KEYS
gpg --verify "$PKG.asc" "$PKG"

shasum must print OK. gpg must print Good signature, with no word that the key has expired or has been revoked. If it has, do not use the package, and ask on dev@skywalking.apache.org. A warning that the key is not certified with a trusted signature is expected.

On Windows, in PowerShell, this must print True. For the signature, install Gpg4win and run the same gpg commands.

(Get-FileHash -Algorithm SHA512 $Pkg).Hash -eq (Get-Content "$Pkg.sha512").Split(" ")[0]

Build from the source package

With Go 1.27 or later:

SRC=apache-skywalking-ai-sessionizer-$VERSION-src.tgz
curl -fL -o "$SRC" "https://www.apache.org/dyn/closer.lua?path=skywalking/ai-sessionizer/$VERSION/$SRC&action=download"
curl -fLO "https://downloads.apache.org/skywalking/ai-sessionizer/$VERSION/$SRC.sha512"
curl -fLO "https://downloads.apache.org/skywalking/ai-sessionizer/$VERSION/$SRC.asc"

Verify it with $SRC in place of $PKG, then:

tar -xzf "$SRC"
cd apache-skywalking-ai-sessionizer-$VERSION-src
make build VERSION=$VERSION
./bin/asz version

make build writes bin/asz and bin/asz-changes. Without make, on Windows for example:

go build -ldflags "-X main.version=$VERSION" -o bin/asz.exe ./cmd/asz
go build -ldflags "-X main.version=$VERSION" -o bin/asz-changes.exe ./plugins/claude-code

A build from source draws the page with system fonts. The binary packages carry the page’s fonts.

go install

This builds the tagged source, not the voted release:

go install "github.com/apache/skywalking-ai-sessionizer/cmd/asz@v$VERSION"

asz version then prints dev, and the Claude Code plugin’s binary is not installed.

Upgrading from 0.4.0

0.5.0 renamed the change recorder, its package and its plugin; the changelog lists every name. The upgrade keeps every record, in this order:

Stop Claude Code and the collector (asz collect or asz server).
Install 0.5.0 by the way you installed 0.4.0. Each way installs both programs now: the install script, brew upgrade asz, or sudo apt install asz asz-changes.
Start the collector again. It reads the plugin’s old directory and its new one.
Run the Claude Code plugin installer for 0.5.0. It carries the plugin’s data across, uninstalls the plugin under its old name with the data kept, and installs it under the new one, whose hooks call asz-changes.
Start Claude Code.
Only then remove what 0.4.0 installed: brew uninstall asz-claude-code or sudo apt remove asz-claude-code. Until step 4 the old plugin’s hooks still call asz-claude-plugin, which those packages hold.

AI Sessionizer