Claude Code Plugin

The plugin records which files each tool call changed, including shell commands and edits inside subagents. asz collects the records, and the conversation page shows each change beside the step that made it. Claude Code Plugin Internals explains what is recorded and how.

Install

Install Claude Code first. Use the same version as the asz you run, from the downloads page.

On macOS or Linux:

VERSION=<version>
curl -fsSL "https://raw.githubusercontent.com/apache/skywalking-ai-sessionizer/v$VERSION/install/claude-code-plugin.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/claude-code-plugin.ps1"))) $Version

The script puts asz-changes in ~/.local/bin, or %USERPROFILE%\.local\bin on Windows, and installs the plugin into Claude Code. Restart Claude Code afterwards.

With Homebrew, install the binary with brew install apache/skywalking-ai-sessionizer/asz, which carries both programs, then run the commands under By hand.

By hand

Put asz-changes from the binary package in a directory on your PATH.

Install the plugin. In a shell:

claude plugin marketplace add "https://github.com/apache/skywalking-ai-sessionizer.git#v$VERSION" --sparse .claude-plugin plugins/claude-code/plugin &&
  claude plugin install file-changes@skywalking-ai-sessionizer

In PowerShell:

claude plugin marketplace add "https://github.com/apache/skywalking-ai-sessionizer.git#v$Version" --sparse .claude-plugin plugins/claude-code/plugin
if ($LASTEXITCODE -eq 0) { claude plugin install file-changes@skywalking-ai-sessionizer }

Check

asz-changes version
claude plugin list

The plugin writes its records under ~/.claude/plugins/data/file-changes-skywalking-ai-sessionizer/, or under CLAUDE_CONFIG_DIR when that is set. If a shell command leaves no record there:

If Claude Code reports Executable not found in $PATH: "asz-changes", it cannot find the binary. Put the binary’s directory on PATH, and start Claude Code from that terminal.
Otherwise, read log/plugin.log in the same directory.

An Edit or Write in the main conversation leaves no plugin record. Claude Code records those changes itself, and asz reads them from the transcript.

Upgrade

Run the install script again with the new version. It keeps the plugin’s settings and the records asz has not collected yet. Coming from 0.4.0 or earlier, it finds the plugin under its old name, asz-changes, carries its data across, and uninstalls it with the data kept. See Upgrading from 0.4.0 for the order to do it in.

By hand, first move asz-changes to the new version: brew upgrade asz, sudo apt update && sudo apt upgrade, or the binary from the new version’s binary package. asz-changes version must print it. Then, in a shell:

(
  set -eu
  : "${VERSION:?set VERSION to the version to move to}"
  claude plugin uninstall file-changes@skywalking-ai-sessionizer --keep-data
  claude plugin marketplace remove skywalking-ai-sessionizer
  claude plugin marketplace add "https://github.com/apache/skywalking-ai-sessionizer.git#v$VERSION" --sparse .claude-plugin plugins/claude-code/plugin
  claude plugin install file-changes@skywalking-ai-sessionizer
)

In PowerShell:

& {
  if (-not $Version) { throw "set `$Version to the version to move to" }
  $Steps = @(
    @("plugin", "uninstall", "file-changes@skywalking-ai-sessionizer", "--keep-data"),
    @("plugin", "marketplace", "remove", "skywalking-ai-sessionizer"),
    @("plugin", "marketplace", "add", "https://github.com/apache/skywalking-ai-sessionizer.git#v$Version", "--sparse", ".claude-plugin", "plugins/claude-code/plugin"),
    @("plugin", "install", "file-changes@skywalking-ai-sessionizer"))
  foreach ($Step in $Steps) {
    & claude @Step
    if ($LASTEXITCODE -ne 0) { throw "claude $Step failed, so the steps after it did not run" }
  }
}

Keep this order. Removing the marketplace, or uninstalling without --keep-data, deletes the plugin’s data.

Remove

claude plugin uninstall file-changes@skywalking-ai-sessionizer
claude plugin marketplace remove skywalking-ai-sessionizer

This deletes the plugin’s data. Run asz collect -once first to keep its records in asz.

Settings

Optional. Put settings.yaml in the plugin’s data directory. These are the defaults:

roots: []                     # empty: the session's project directory
exclude:
  defaults: standard-v1
  add: []
  remove: []
read_only:
  enabled: true
tools:
  scope: [Bash, PowerShell, Monitor]
retention:
  idle: 30m
  ttl: 720h
scan_timeout: 30s
size_cap: 1048576

roots: the directories watched.
exclude: directories never watched. standard-v1 holds the build output and caches of common languages and tools; Exclusions lists them. add adds rules and remove drops a default. A rule that starts with / is relative to the root; any other name matches at any depth.
read_only.enabled: skip the scan around a shell command that only reads.
tools.scope: the tools watched with a scan.
retention.idle: drop the saved file contents of a root that has been idle this long.
retention.ttl: delete an output file not written for this long.
scan_timeout: stop a scan after this long, and mark its record partial. Keep it well under 60 seconds, after which Claude Code stops the hook and nothing is recorded.
size_cap: record a larger file by its hash only.

With CLAUDE_PLUGIN_DATA set to the data directory, asz-changes status prints the settings in force, and asz-changes prune applies the retention rules now.

AI Sessionizer