Telemetry & privacy

Check exactly what fallow telemetry sends before you turn it on. Telemetry is opt-in and off by default, sends no identifiers, and you can print the payload before you consent.

Fallow telemetry is opt-in and off by default. This page lists what fallow sends when you turn it on, and what it never sends. The data helps improve agent, CI, JSON, MCP, and editor workflows. Fallow does not use it to track individuals or codebases. For the commands and environment controls, see fallow telemetry.

To keep telemetry off everywhere, set FALLOW_TELEMETRY_DISABLED=1 or DO_NOT_TRACK=1. See Disabling everywhere.

What is never collected

Fallow telemetry never includes:

repository, organization, project, branch, or git remote names
file paths, import specifiers, source snippets, or stack traces
package, dependency, workspace, or framework package names
raw command-line arguments
config contents or config values
environment variable names or values
raw errors, logs, or serialized exceptions
machine, user, project, or repository identifiers

Fallow does not send hashed versions of these values either.

The one exception is an anonymous install grouping token. With this token, aggregate dashboards can count distinct workflows per install instead of per run. The token has these properties:

It is a new random value. Fallow never derives it from your machine, user account, repository, project, file paths, or environment.
Fallow creates it only when you explicitly opt in: fallow telemetry enable, or the first upload after FALLOW_TELEMETRY=on.
fallow telemetry disable deletes it.
Fallow sends it only as a private transport header (X-Fallow-Install) for server-side grouping. It is never a field inside the event.
fallow telemetry status reports only whether the token is present. It never shows the token.

Inspect what is sent

You do not have to trust the list. To print the exact payload that a real command would send, without sending it, run:

FALLOW_TELEMETRY=inspect fallow audit --format json --quiet

Fallow prints the payload to stderr. The normal output of your command does not change.

What is collected

When you enable telemetry, fallow records one small, high-level event per analysis run. A successful run gives a workflow_completed event. A failed run gives a workflow_failed event. To print this example, run fallow telemetry inspect --example:

{
  "schema_version": 2,
  "event": "workflow_completed",
  "fallow_version": "3.31.0",
  "workflow": "audit",
  "integration_surface": "mcp",
  "invocation_context": "agent",
  "agent_source": "codex",
  "output_format": "json",
  "quiet": true,
  "ci": false,
  "tty": false,
  "os": "macos",
  "arch": "aarch64",
  "duration_bucket_ms": "500-2000",
  "outcome": "issues_found",
  "exit_code_bucket": "1",
  "run_scope": "changed_only",
  "config_shape": "custom_rules",
  "output_destination": "stdout",
  "analysis_mode": "static",
  "file_count_bucket": "500-1999",
  "function_count_bucket": "1000-9999",
  "avg_fan_out_bucket": "1-2",
  "findings_present": true,
  "result_count_bucket": "1-9",
  "report_truncated": true,
  "truncation_reason": "comment_limit",
  "cache_state": "warm",
  "mcp_tool": "find_dupes",
  "has_parent_run": true,
  "run_role": "followup",
  "followup_kind": "audit"
}

Many fields are optional. Fallow omits a field when it does not apply to the run:

agent_source appears only on agent-driven runs.
failure_reason appears only on workflow_failed events.
mcp_tool appears only when a run came through the MCP server.
truncation_reason appears only when report_truncated is true.
The scale buckets, findings_present, result_count_bucket, report_truncated, and cache_state appear only when the workflow computes that value.

Field	Purpose
`workflow`	Prioritize the audit, dead-code, health, duplication, CI, runtime-coverage setup, impact, security, fix, and explain workflows.
`integration_surface`	Show whether you use fallow through human CLI, CLI JSON, MCP, CI, editor, or as a library.
`invocation_context`	Separate human, CI, editor, and agent-driven use without uploading detection evidence.
`agent_source`	Improve compatibility with specific agent integrations. Values come from a documented allowlist.
`output_format` / `quiet`	Protect the output contracts that users and agents rely on most.
`duration_bucket_ms`	Find slow workflow classes without collecting exact timings.
`outcome` / `exit_code_bucket`	Measure clean runs, findings, and failures without uploading raw error text.
`failure_reason`	Group failed runs into a fixed allowlist: `validation`, `unsupported_format`, `config`, `analysis`, `diff`, `network`, `auth`, `gate`, `signal`, or `unknown`. Fallow never parses raw error text for it.
`run_scope`	Classify the run as `full_project`, `changed_only`, `workspace_scoped`, or `file_scoped`, without names or refs.
`config_shape`	Classify the config as `default`, `custom_config`, `custom_rules`, or `plugins_enabled`, without paths, rule names, plugin names, or values.
`output_destination`	Classify the report destination as `stdout`, `file`, or `ci_comment`, without paths or URLs.
`analysis_mode`	Classify the analysis family (`static`, `runtime_coverage`, `production_coverage`, `security`, `similar_code`, or `fix`), without raw command lines.
`file_count_bucket` / `function_count_bucket` / `avg_fan_out_bucket`	Coarse project scale from counts that the workflow already computed. Exact counts never leave your machine.
`findings_present`	Whether the analysis found any issues, independent of the exit code. This makes informational analyses measurable, such as default-config `dupes`, which never exits non-zero.
`result_count_bucket`	Coarse result volume: `0`, `1-9`, `10-99`, `100+`, or `unknown`.
`report_truncated` / `truncation_reason`	Whether a report or PR comment was cut short, and why (`comment_limit`, `max_items`, `size_limit`, or `unknown`).
`cache_state`	Segment the duration of combined runs by cache state: `cold`, `warm`, `partial`, or `unknown`.
`mcp_tool`	Attribute MCP usage to a specific tool, from a fixed allowlist of tool names.
`has_parent_run` / `run_role` / `followup_kind`	Separate root runs from agent follow-up runs, and classify the follow-up by workflow. The event never contains the correlation token.

Two values travel as private HTTP headers, never as fields in the event:

X-Fallow-Parent-Run: a sanitized correlation token for follow-up runs. Fallow sends it only when a run is explicitly linked to a previous one.
X-Fallow-Install: the anonymous install grouping token described above.

When fallow runs through the MCP server, the server tags the CLI process that it starts. The one event from that run then counts toward the mcp surface and the specific tool, instead of a plain cli_json run. Code Mode snippets can make several read-only host calls. Fallow attributes the CLI events from those calls to code_execute, not to free-form code text or nested helper names. This tagging sends no extra event and does not change what fallow collects.

The LSP server, editor extension, and library embeddings run in-process and currently emit no telemetry.

The schema_version field increments if the collected fields change. The fallow team updates this page before any new field ships.

Agent source

When telemetry is enabled and fallow classifies a run as agent-driven, fallow may send one normalized agent_source value from a fixed allowlist:

none codex claude_code cursor copilot opencode aider roo
windsurf gemini cline continue zed goose other_known unknown

Fallow never sends none. It is the internal default before fallow classifies a run, and fallow sends agent_source only for agent-driven runs. Fallow groups agents that are not on the list, for example enterprise IDE assistants, under other_known. Fallow also normalizes aliases: hyphen aliases such as claude-code, and CLI aliases such as gemini_cli and antigravity (both map to gemini).

Fallow does not upload any of these:

raw MCP client info
process names or parent process paths
editor or extension identifiers
environment variable names
model names
account or organization IDs
prompts
versions
free-form vendor strings

If you write an agent wrapper, set FALLOW_AGENT_SOURCE=<allowlisted-value>. Fallow ignores a value that is not on the allowlist, and then sends no agent_source. If your wrapper cannot name the agent, set FALLOW_AGENT_SOURCE=unknown. Setting FALLOW_AGENT_SOURCE never enables telemetry by itself and uploads no codebase content. When more than one agent environment is present, attribution is best-effort and can depend on check order. To name the agent yourself, set FALLOW_AGENT_SOURCE.

Transport and server privacy

Fallow sends each request as an HTTPS POST with a JSON body to https://api.fallow.cloud/v1/telemetry/events (override the host with FALLOW_API_URL)
Fallow uses no cookies and sends no authentication token
At exit, fallow writes the event to a local spool file (telemetry-spool.jsonl, next to the user-level telemetry config). It does not upload the event during the run that produced it
At the start of the next telemetry-enabled run, a background thread uploads the spooled events. The upload does not slow down your command
Delivery is best-effort. The spool keeps at most the 64 newest events, so a machine that stays offline drops its oldest events. The counts are a rough sample, not an exact usage count
Fallow ignores network errors, and they never affect command output or the exit code
Fallow never writes telemetry to stdout
The server does not add customer, repository, organization, git, package-registry, or license data to telemetry
The server drops or truncates IP addresses as early as practical
The server keeps raw events for a short window only, then deletes them

Public reporting uses only coarse aggregate trends after privacy review.

Disabling everywhere

The DO_NOT_TRACK and FALLOW_TELEMETRY_DISABLED environment variables are kill switches with top precedence. When either is truthy, telemetry stays off and fallow refuses fallow telemetry enable. In managed and CI environments, use FALLOW_TELEMETRY_DISABLED=1 as the fleet-wide switch.