Skip to content
Sonomos Docs

How to install Canary in Claude Code (two slash commands)

Canary installs as a Claude Code plugin. The whole thing takes about a minute.

Requirements

  • Claude Code installed and signed in. See the Claude Code install guide if you don’t have it yet.
  • A POSIX-y environment — macOS or Linux. Windows is supported via WSL2.
  • bash and jq on your PATH. Both are present by default on macOS and most Linux distros. If jq is missing, install it with brew install jq (macOS) or apt-get install jq (Debian/Ubuntu).
  • Write access to your home directory (Canary stores findings in ~/.sonomos/).

No Sonomos account is required. Canary is fully local and open source.

Install

  1. Add the Canary marketplace to your Claude Code plugin sources. In a Claude Code session, run:

    /plugin marketplace add sonomos-ai/Canary-Plugin

    This tells Claude Code where to find Canary releases.

  2. Install the plugin:

    /plugin install canary@sonomos

    Claude Code downloads the plugin, registers the slash commands, and creates ~/.sonomos/ for local findings storage.

  3. Verify the install by running the dashboard command — even with zero detections, it should open:

    /canary:leaked

    You should see Canary’s HTML dashboard (or, on terminals without a browser, the stats summary).

Optional: persistent statusline

Canary can display a running PII counter in your Claude Code status line, coloured by severity (green / yellow / red). Add the following to ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "bash ~/.sonomos/statusline.sh"
  }
}

Restart Claude Code. You’ll see the current detection count whenever Canary is active. The number is intentionally only ever incremented — it gives you an honest, persistent picture of your AI exposure across sessions.

Verify everything is working

Run a quick smoke test inside a Claude Code session:

  1. Ask Claude something innocuous that contains a fake credential, e.g. Explain what AWS access key AKIAIOSFODNN7EXAMPLE is. Use only fake / well-known example values.
  2. Wait a moment for the async scan to settle.
  3. Run /canary:leaked stats. You should see at least one detection in the AWS access key category.
  4. Run /canary:leaked reset to clear the smoke-test data when you’re done.

Updating Canary

To update to the latest release:

/plugin update canary@sonomos

Major changes are noted in the Canary release notes on GitHub.

Uninstalling

/plugin uninstall canary@sonomos

The plugin is removed from Claude Code. Your detection history at ~/.sonomos/ is not automatically deleted — that data belongs to you. To wipe it manually:

Terminal window
rm -rf ~/.sonomos

Next steps

How Canary works The detection pipeline, async scanning, and where data is stored.
Commands & dashboard Every slash command and CLI tool Canary ships with.
Privacy & security What's stored, how it's redacted, and the threat model.