Telemetry & Analytics

At Zillowe, we are committed to protecting your privacy while also working to improve our application. To achieve this, we use an opt-in telemetry system that collects a minimal amount of anonymous data. This data helps us understand which packages are popular and which platforms are most commonly used, allowing us to prioritize our development efforts.

This page aims to be radically transparent about what we collect, why we collect it, and how you can control it.

What We CollectCopy Anchor Link

When you choose to enable telemetry, Zoi sends secure, anonymous events through two official Rust SDKs:

• PostHog (posthog-rs) for usage analytics, sent to an EU PostHog cloud-hosted (https://eu.i.posthog.com) instance when you perform certain actions. Delivery is asynchronous: commands only append small event files to $XDG_STATE_HOME/zoi/telemetry/queue/ (fast local I/O, no network) and spawn a detached zoi telemetry flush worker that uploads them after your command has already exited. A slow network therefore never stalls the CLI, and events that fail to upload stay queued for the next run instead of being lost. The queue holds at most 100 files and drops anything older than 30 days.
• Sentry (sentry crate with network transport) for error tracking. Failed commands are reported to Sentry automatically while opted-in (error message, cause chain, and stacktrace, tagged with the command name). Crash files you approve are uploaded the same way.

Scope: telemetry applies to the main zoi CLI and follows the user's opt-in. The lightweight zoi-mini helper never sends telemetry, even when telemetry is enabled.

The data we collect is strictly limited to the following fields:

• Event Type: The action you performed. This can be one of the following:
  • install: A package was successfully installed (including packages installed as dependencies or via update, exec, or shell -p).
  • uninstall: A package was uninstalled.
  • dau: A bare daily active-user ping carrying no command or package identity, just the anonymous client ID plus environment fields. It is queued at most once per 24 hours (the last-queue time is tracked in the user state dir) and is what powers DAU/WAU/MAU counts: any ping marks the anonymous client ID active for that period. Like all PostHog events it uploads in the background after your command exits.
• Failures: Failed commands are reported to Sentry for error tracking (message plus error chain, tagged with the command name). They are never sent to PostHog, keeping usage analytics separate from errors. Unhandled panics are saved as local crash reports (see below).
• A unique, anonymous client ID: This is a randomly generated UUID that is not tied to any of your personal information. It allows us to distinguish between usage patterns from many users versus a single power user, which helps in prioritizing features.
• Package Details:
  • The name of the package.
  • The sub_package name (if applicable).
  • The version of the package.
  • The package's repo (the sub-repository path, e.g. core, community/editors).
  • The description of the package.
  • The license of the package.
  • The maintainer and author of the package (name, email, and website, if provided).
• Registry Details:
  • The registry handle (e.g. zoidberg, my-custom-registry).
  • The registry_url (the git URL of the registry).
• The type of package: This will be one of Package, Collection, App, or Extension.
• The installation scope: One of User, System, or Project.
• The installation reason: One of Direct or Dependency.
• The installation type: One of source or pre-compiled.
• Your Environment:
  • Your operating system and CPU architecture (e.g. linux-amd64, windows-amd64).
  • Your Linux distribution (e.g. ubuntu, arch).
  • Your detected shell (e.g. zsh, fish).
  • The version of the Zoi application you are using.

Success analytics (PostHog) never include personal information. We do not track your IP address, hostname, or any data not explicitly listed above. Failure reports (Sentry) are different by nature: error messages and stacktraces can inadvertently contain local file paths, so treat them as potentially sensitive. The code that collects and sends this data is fully open-source and can be reviewed in crates/telemetry/src/lib.rs.

Why We Collect ItCopy Anchor Link

The data we collect helps us answer important questions that guide the development of Zoi:

• Which packages are the most popular? This helps us focus our maintenance efforts on the tools that matter most to the community.
• Which operating systems and architectures are most widely used? This informs our decisions about which platforms to prioritize for testing and binary releases.
• Which custom registries are being used? This helps us understand how the community is extending Zoi.
• Are there errors we need to address? Failed commands send their error message, cause chain, and a stacktrace to Sentry.

By understanding how Zoi is used, we can make it a better tool for everyone.

How to Manage TelemetryCopy Anchor Link

Telemetry in Zoi is disabled by default. You must explicitly opt-in to share anonymous data with us. You can manage your telemetry settings at any time using the zoi telemetry command.

Check Your StatusCopy Anchor Link

To see whether telemetry is currently enabled or disabled, run:

zoi telemetry status

Enable TelemetryCopy Anchor Link

If you would like to help us improve Zoi, you can enable telemetry by running:

zoi telemetry enable

Disable TelemetryCopy Anchor Link

You can disable telemetry at any time. Zoi will immediately stop sending anonymous data.

zoi telemetry disable

Crash ReportsCopy Anchor Link

Zoi has a built-in crash reporter inspired by Ghostty. When Zoi panics, it saves a crash report to disk. Crash reports are saved to the $XDG_STATE_HOME/zoi/crash directory (default ~/.local/state/zoi/crash on Linux). Crash reports are not automatically sent anywhere off your machine.

Crash files use the .zoicrash extension and contain a Sentry envelope (header line, item-header line, event-payload line with panic message, backtrace, OS/arch, release, and environment). You can upload these to your own Sentry account with the SDK-backed sender or with sentry-cli, and any tool that reads Sentry envelopes can inspect them.

If telemetry is enabled, the next time you start Zoi after a crash it will ask whether to upload each pending report. If telemetry is disabled, reports are only saved locally and you are never prompted.

# List stored crash reports
zoi telemetry crash list

# Print a report envelope to stdout
zoi telemetry crash show <file>

# Upload a report to Sentry (requires telemetry opt-in)
zoi telemetry crash send <file>

# Delete all stored reports
zoi telemetry crash clear

To send a crash report to the Zoi project manually with the Sentry CLI:

SENTRY_DSN="https://c8d665d2f696aa636baa4b68ff4a44c0@o4511544490459136.ingest.de.sentry.io/4511544501600336" sentry-cli send-envelope --raw <path to crash report>

Warning: a crash report can contain sensitive information. The report does not purposely contain sensitive data, but it does contain a backtrace and runtime context captured at the time of the crash, which may include sensitive values depending on when the crash occurred. Review a report with zoi telemetry crash show before uploading it.

We are grateful to everyone who chooses to opt-in. Your anonymous contributions are invaluable in helping us build a better package manager.