Our Tools Will Send Anonymous Usage Statistics

By the Pipelex team

Starting with their coming releases, the tools you install and run yourself will send anonymous usage statistics to Pipelex. They are the Pipelex runtime, with its pipelex and pipelex-agent command-line tools and its self-hosted API server; plxt and the Pipelex extension for VS Code; and the mthds command-line tool. The statistics are counts of commands, runs, pipe types, models and tokens, with the country your IP address maps to. They never include your methods, prompts, inputs, outputs, file names or pipe names.

They will be on by default, and turning them off takes one step. We are announcing this before any of it ships, so that nobody learns about it from a notice in their terminal. This post says which tools send what, what they never send, why we want it, how to turn it off, and how to have your statistics deleted.

Which tools, and from which release

The Pipelex runtime: the pipelex and pipelex-agent command-line tools, the self-hosted API server and its Docker image, and any Python program you write that imports pipelex.
plxt, the formatter and linter for MTHDS and TOML files, and the Pipelex extension for VS Code.
The mthds and mthds-agent command-line tools of the MTHDS open standard.

Each tool starts sending statistics from the release whose changelog announces them. Earlier releases send none, so nothing changes until you upgrade.

Some things never send these statistics: our other libraries and our SDKs, which other people build into their own products; anything that runs in a web browser; and Pipelex Cloud, whose runs are already counted by the product analytics described in section 3 of our privacy policy.

Why we want them

These tools are open-source and source-available, and people run them on their own machines and servers, where we see nothing. We do not know how many installations are active, which commands people run, which pipe types and models their methods use, or how often runs fail and where. When someone tries Pipelex once and gives up, we cannot tell whether a run failed, at which command they stopped, or which models they tried.

Counts answer those questions and tell us where to put our work. We chose to have them on by default, as Homebrew and Next.js do, because statistics that people must first switch on count only the few who do, and miss the people who try a tool once, who are the ones we most need to understand. In return, we hold ourselves to collecting little, saying exactly what, making it one step to turn off, and never getting in your way. Once the numbers are stable, we plan to publish the totals, which describe no single installation.

What you will see

The first time one of these command-line tools runs on your machine with statistics on, it prints a notice on stderr before the command does its work, so that the output of your commands stays clean. As the runtime prints it:

Pipelex collects anonymous usage statistics: counts of commands, runs, pipe types, models and tokens, and the country your IP address maps to; the address itself is never stored. It never collects your methods, prompts, inputs, outputs, file names or pipe names. To turn it off, run pipelex usage-stats disable or set DO_NOT_TRACK=1. Details: https://docs.pipelex.com/latest/setup/usage-statistics/

Each tool names its own way to turn it off. On the command line and in the VS Code extension, the notice appears once per machine, whichever tool runs first, because every tool records that it was shown in the same place. The extension shows it as a message with buttons to disable the statistics or read the details. The self-hosted server, and a Python program that imports the runtime, write it to their log once at startup. pipelex init shows it every time it runs while statistics are on.

Where a tool's error output is read by a program rather than a person, as with pipelex-agent reporting its errors as JSON and with mthds-agent, the notice is not printed, but the statistics are still sent, and the next command whose output you read prints it.

The first run is counted. The notice comes before that run's statistics are sent, but they are sent. If you want nothing sent at all, turn the statistics off before your first run of a new release, with any of the switches below.

What is sent

Every value sent is a count, a yes-or-no, a version, a value from a fixed list, a time or a random identifier. No field can hold text you wrote, and the PostHog project that receives the events refuses any event or property that is not on the list our documentation describes.

The Pipelex runtime sends:

one event per run, whatever started it and however it ended: whether it succeeded, failed or was cancelled; for a failure, who can fix it (your input, your configuration or the runtime), from a fixed list and never the error's message; whether it was a dry run; the kind of source the method came from, such as a local bundle or a published address, never the address itself; its duration; the size and nesting depth of the bundle; which language features it uses, such as batching, parallel branches, conditions, structured outputs, and image or document inputs; how many pipes of each built-in type ran; and its totals of inference calls, failures, tokens, images generated, pages extracted and estimated cost in US dollars, computed from the release's own price tables when they know every model used;
one event per model a run used: the kind of backend it was called through, from the list the runtime ships, or custom for any other; the model's name as the release's own model tables give it, or other, so that the name of a private deployment or a fine-tuned model never leaves your machine; and that run's calls, failures by category, tokens, images, pages and cost for that model;
one event per command of pipelex and pipelex-agent: the command's name, such as run pipe or validate bundle, never its arguments or options; its outcome and duration; whether it ran on the hosted API; and for pipelex init, where it set runs to execute and which kinds of backend it enabled;
one event per validation of a method, with its verdict, its duration, its numbers of errors and warnings and the size and depth of the bundle, and one per code generation, with what was generated and, for types, the target language, the outcome, the duration and the size of the bundle.

plxt sends one event per format, lint, get or config command: its outcome and duration, how many files it processed in ranges such as 2 to 10, what started it (a terminal, a pre-commit hook, continuous integration or something else), and how many syntax, semantic and schema diagnostics it reported. It sends nothing while it serves as a language server.

The VS Code extension sends at most one event a day when it starts, naming the editor (VS Code, Cursor, Windsurf, VSCodium and the like) and its version, and counts of how often you use its graph preview, validation, run and formatting, sent in small batches every few minutes.

The mthds CLI sends one event per command of mthds and mthds-agent: the command's name, never its arguments; its outcome; who can fix a failure, when it can tell; its duration; and, for a run, whether it went to the hosted API.

Every event also carries the tool's name and version, and which of its entry points sent it, such as a command-line tool, the API server, a Python program or the extension; for the runtime, its integration mode; your operating system family and processor architecture; the major and minor version of Python, or the major version of Node.js, for the tools that run on them; whether it runs in continuous integration or in a container; the name of the program of ours that started the tool, when one did and says so; which version of the notice the machine has seen; whether this process created the installation identifier; and whether the machine is marked as one of our team's, so that our own use can be left out of the numbers.

Your country. PostHog, which receives the events, sees your IP address with each request, as any web server does. It derives the country from it, and the project stores neither the address nor any finer location, such as a city, a region or coordinates.

An installation identifier. The first of our tools to run on your machine draws a random identifier and keeps it in ~/.mthds/usage-stats/, where every other tool reads it. It lets us count installations rather than events, and follow an installation from one tool to the next, for instance from mthds install to a first pipelex run. It is never derived from your machine's name, your user name, a network address, a path or anything else about you or your computer, and you can replace it at any time. No profile of a person is created from it. A CI runner or a container that keeps no state draws a new identifier each time, which is why every event says whether it comes from CI or a container.

What is never sent

No event carries your methods or their MTHDS source; the names of your pipes, concepts, domains or classes, or any other name you wrote; prompts, inputs, outputs or generated content; file names, paths, URLs or repository addresses; method names, catalog identifiers or run identifiers; error messages, stack traces or exceptions; command arguments or option values; the values of environment variables; machine names, user names or email addresses; IP addresses or any location finer than the country; or the order in which a run's pipes executed.

Every tool carries a test that runs its commands on a method whose every name, prompt, input, file name and error message contains a unique marker, and fails if that marker appears anywhere in what the tool would send or store.

One exception predates this change. When you install or publish a method from a public repository with mthds or mthds-agent, the CLI sends an event carrying the public fields of that method's manifest, such as its address, name, version, description and authors, so that the MTHDS Hub at mthds.sh can count installs and rank methods. These events carry no user identifier, nothing is sent for a private repository, and the CLI asks PostHog not to derive a location from them. They follow fewer switches than the statistics, as the next section explains. Publishing itself does not depend on them: the release of mthds that brings the statistics lists a published method on mthds.sh directly, whatever your settings.

How it is sent

The statistics go straight to PostHog's European Union region, into a project that holds nothing but these statistics. Sending never gets in your way. A command-line tool writes its events to a small queue when the command ends, starts a background sender and exits at once, and the sender posts the queue within seconds. If you are offline, the events wait in the queue for the next command's sender, and the queue is bounded, so it never grows without limit. In continuous integration or in a container, where a background process would be killed, the command posts its events itself before exiting, waiting at most one second. The server, the extension and Python programs post in the background while they run. A failure to send is silent and never changes what your command or your run does.

How to turn them off

The statistics are on unless any one of these switches says off, and no switch can turn them back on over another that says off. Every tool reads them before its command does anything, so a command run with statistics off is never counted.

DO_NOT_TRACK=1, the cross-tool convention, set to any value but empty, 0 or false. It turns off everything our tools send to Pipelex, the mthds install and publish events included. In the runtime it also turns off the custom telemetry you send to your own observability backends through telemetry.toml; to keep that, use PIPELEX_USAGE_STATS=0 instead.
PIPELEX_USAGE_STATS=0, or false, no or off. It turns off the statistics of every one of these tools, the mthds CLI's included, and a value it cannot read turns them off too. It does not turn off the mthds install and publish events.
DISABLE_TELEMETRY=1 in the environment, for the mthds and mthds-agent CLIs. It turns off their statistics and their install and publish events.
The choice for your machine: pipelex usage-stats disable, plxt usage-stats disable, mthds telemetry disable, or Pipelex: Disable Usage Statistics in VS Code's command palette. Any one of them turns the statistics off for every tool on the machine, the mthds install and publish events included, and deletes the events still waiting to be sent; a server or an extension that is already running stops before its next send. The matching enable command, in any of these tools, turns the machine's choice back on and tells you when another switch still keeps the statistics off.
The choice you already made with mthds: if mthds telemetry disable in an earlier release wrote DISABLE_TELEMETRY=1 to ~/.mthds/config, every tool honours it, and the first one to run carries it into the choice for your machine.
A project setting, for a team: enabled = false in the [usage_stats] section of a project's committed .pipelex/pipelex.toml turns the statistics off for everyone who works in that project. A project can only turn them off, never on, and a file that cannot be read as this setting turns them off as well. It does not turn off the mthds install and publish events.
VS Code's own telemetry setting, its enterprise policy included, for the extension, followed as soon as it changes. The programs the extension starts, such as pipelex-agent for validation, send no statistics of their own: the extension counts their use itself, under that setting.
A packaged default: a distribution or a company image can ship the runtime with enabled = false in the [usage_stats] section of its packaged configuration, which turns the statistics off for every user of that installation.

Two more switches exist for testing: the runtime's pytest integration mode, which test suites use, turns the statistics off, and so does PIPELEX_USAGE_STATS_ENDPOINT, which points the senders at a test server on your own machine, whenever it is set to anything but such a local address.

In practice:

export DO_NOT_TRACK=1          # everything, in every tool
pipelex usage-stats disable    # this machine, every tool
export PIPELEX_USAGE_STATS=0   # the statistics only, in this shell

# .pipelex/pipelex.toml, committed to the project
[usage_stats]
enabled = false

For the self-hosted server's Docker image, pass either variable to the container, for example with docker run -e PIPELEX_USAGE_STATS=0.

Seeing exactly what is sent

pipelex usage-stats status, plxt usage-stats status and mthds telemetry status, or Pipelex: Show Usage Statistics Status in VS Code, say whether the statistics are on, which switches keep them off, and your installation identifier. On the command line, --format json prints the same as one JSON object.
PIPELEX_USAGE_STATS_DEBUG=1 makes every tool print each event, exactly as it would be sent, as one line of JSON on stderr, and send nothing. The extension writes these lines to its output channel. The switches still decide, so nothing is printed while the statistics are off.
pipelex usage-stats reset-id, plxt usage-stats reset-id or mthds telemetry reset-id replaces your installation identifier with a new random one and discards the events still waiting to be sent.

Deleting your statistics

To have the statistics of your installation deleted, write to privacy@pipelex.com with its identifier, which the status command of any of these tools shows. Turn the statistics off or reset your identifier first, because a deletion covers only what was sent before your request. To delete them, PostHog needs a profile for that identifier, so we create one only to delete it along with your statistics.

How long we keep the statistics, on which legal basis we process them, and your rights are set out in section 5 of our privacy policy.

Our privacy policy, whose section 5 covers these statistics.
Usage Statistics in the Pipelex documentation, the page the notice links to, with every event and every switch.
The pipelex usage-stats commands.
Usage statistics in plxt and the VS Code extension.
Usage statistics in the mthds CLI.

If you have questions or concerns, tell us on Discord.