Telemetry

NimbleBrain collects anonymous usage telemetry to improve the platform. Telemetry is on by default and can be disabled at any time. No personal data, conversation content, or file paths are ever sent.

What is collected

Telemetry events fall into four categories:

CLI events

Event	Properties
cli.startup	Mode (serve), bundle count, startup time in ms

Agent loop events

Event	Properties
agent.chat_started	Whether a skill matched, tool count, whether this is a resumed conversation
agent.chat_completed	Iteration count, tool call count, stop reason (complete, max_iterations, token_budget), LLM latency, tool latency, total time, input/output token counts
agent.error	Error type name only (e.g., AnthropicError), structured error code if available

Bundle lifecycle events

Event	Properties
bundle.installed	Source type (mpak, local, remote), whether it has UI, trust score
bundle.uninstalled	Source type

Web client events

Event	Properties
web.page_view	Automatic (PostHog JS), IP capture disabled
web.chat_sent	Whether this is a resumed conversation, whether an app context is set
web.app_opened	Whether the app has a primary view

What is never collected

• Conversation content, messages, or prompts
• File paths, working directories, or hostnames
• Usernames, IP addresses, or email addresses
• Bundle names, skill names, or tool names
• Tool arguments or results
• Error messages or stack traces (only error type)
• Model names (could reveal organization info)
• Cost data (reveals pricing tier)

Identity model

On first run, NimbleBrain generates a random UUIDv4 and stores it at ~/.nimblebrain/.telemetry-id. This is the only identifier sent with events. It has no connection to any user identity.

The ID is scoped to the work directory. Running bun run dev (workDir = .nimblebrain) creates a different ID than bun run start (workDir = ~/.nimblebrain).

The web client uses a separate browser-scoped anonymous ID (generated by PostHog JS using in-memory persistence). Server and web events are correlated by a shared installId property.

How to opt out

Any one of these methods disables telemetry completely:

Config file

Add to nimblebrain.json:

{
  "telemetry": {
    "enabled": false
  }
}

Environment variable

export NB_TELEMETRY_DISABLED=1

Or use the informal standard:

export DO_NOT_TRACK=1

Environment variables are checked first (no file I/O). If either is set, telemetry is off regardless of the config file.

Re-enabling telemetry

Telemetry is on by default. Remove the NB_TELEMETRY_DISABLED / DO_NOT_TRACK env vars and set telemetry.enabled: true (or drop the telemetry block) in nimblebrain.json.

Resetting your anonymous ID

To unlink future events from past events, delete ~/.nimblebrain/.telemetry-id. A new random ID is generated on the next run.

First-run notice

On first run, when the .telemetry-id file is created, NimbleBrain prints this notice to stderr:

NimbleBrain collects anonymous usage telemetry to improve the platform.
No personal data, conversation content, or file paths are ever sent.
Set NB_TELEMETRY_DISABLED=1 (or DO_NOT_TRACK=1) to disable.  Learn more: https://nimblebrain.ai/telemetry

This notice appears exactly once per work directory.

Tip

When telemetry is disabled, no .telemetry-id file is created and no HTTP requests are made to PostHog. The PostHog SDK silently drops events when offline — telemetry is always best-effort and never blocks normal operation.

Technical details

• Server-side SDK: posthog-node (batched, async, no native bindings)
• Web client SDK: posthog-js with ip: false, autocapture: false, disable_session_recording: true, persistence: "memory"
• Destination: PostHog Cloud (https://us.i.posthog.com)
• Check order: Environment variables checked first, then config file
• Offline behavior: Events silently dropped (no disk queue, no exceptions)

What’s next

• Configuration: nimblebrain.json — full config reference including telemetry settings
• Environment Variables — NB_TELEMETRY_DISABLED and DO_NOT_TRACK