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.command	Command name (e.g., bundle.add), mode (tui, headless, serve, dev), flag names only (never values), NimbleBrain version, OS, architecture, Bun version
cli.startup	Mode, bundle count, skill 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
bundle.crashed	Source type, uptime before crash, restart count
bundle.recovered	Source type, downtime duration
bundle.dead	Source type, restart count

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 nb dev (workDir = .nimblebrain) creates a different ID than nb serve (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:

CLI command

nb telemetry off

Telemetry disabled.

This sets telemetry.enabled: false in nimblebrain.json.

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

nb telemetry on

Telemetry enabled.

Checking telemetry status

nb telemetry status

Telemetry: enabled
Anonymous ID: a1b2c3d4-5678-9abc-def0-123456789abc
ID file: /home/user/.nimblebrain/.telemetry-id

Events sent:
  - CLI commands (command name, mode, flag names)
  - Agent loop (iterations, tool count, latency, stop reason)
  - Bundle lifecycle (install/uninstall/crash counts)
  - Errors (error type only)

Never sent:
  - Conversation content, file paths, tool arguments
  - Usernames, hostnames, IP addresses
  - Bundle names, skill names, model names

Destination: PostHog (https://us.i.posthog.com)

Resetting your anonymous ID

Generate a new random ID, unlinking future events from past events:

nb telemetry reset

Anonymous ID reset: f9e8d7c6-5432-1abc-def0-fedcba987654

You can also manually delete ~/.nimblebrain/.telemetry-id. A new 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.
Run 'nb telemetry off' 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)
• CLI mode: Events sent immediately (flushAt: 1) since CLI commands are short-lived

What’s next

• Configuration: nimblebrain.json — full config reference including telemetry settings
• CLI: nb telemetry — CLI reference for telemetry commands