Diff Documentation

Getting Started (CLI)

The fastest way to start is with the Diff CLI. It runs as a background service on your machine, watches for coding agent sessions, and uploads them automatically. The CLI is open source.

Install on macOS

brew tap getdiff/tap && brew install getdiff

Install on Linux

curl -fsSL https://github.com/getdiff/homebrew-tap/releases/latest/download/getdiff-$(uname -m)-unknown-linux-gnu.tar.gz | tar xz
sudo mv getdiff /usr/local/bin/

Log in

Run the login command to authorize the CLI with your Diff account. This opens your browser for authentication.

getdiff login

Start the background service

Once logged in, start the watcher so sessions are captured automatically.

macOS (Homebrew)

brew services start getdiff

Linux

# Quick start
getdiff watch &

# Or with systemd (persistent across reboots)
getdiff watch --install-service

That's it. Sessions will appear in Diff automatically as you use your coding agent.

Support Matrix

Both the Diff CLI and OpenTelemetry send the same session data. The table below shows current support for each coding agent across both ingestion methods.

The Diff CLI works as a broad fallback for any agent that writes session data locally. OpenTelemetry requires the agent to emit OTLP natively. When in doubt, start with the CLI.

* Cursor CLI limitations: Due to Cursor's sparse logging, some data is unavailable or best-effort. Timestamps are approximate, and there is no tracking for tool calls/results, token usage, cost, per-message timestamps, git branch, stop reasons, or thinking detection.

OpenTelemetry Setup

For teams that want cross-platform coverage or centralized telemetry control, Diff accepts data via the OpenTelemetry protocol (OTLP). This works on macOS, Linux, and Windows wherever the coding agent emits OTLP natively.

Choose a collector strategy

There are three ways to route telemetry to Diff:

1. Diff's hosted collector — Point your agents directly at otel.getdiff.now. No infrastructure to manage. Best for most teams.
2. Centralized collector — Deploy your own OTel Collector that receives telemetry from all engineer machines and forwards it to Diff. Gives you control over filtering, sampling, and redaction before data leaves your network.
3. Local collector — Run a collector on each machine alongside the coding agent. Useful when you need per-machine processing or when engineers work in air-gapped environments.

Forwarding to Diff from your own collector

If you run your own collector (centralized or local), configure an OTLP exporter that forwards to Diff's ingest endpoint. Here's a minimal OTel Collector config:

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

exporters:
  otlphttp:
    endpoint: https://otel.getdiff.now
    headers:
      Authorization: "Bearer <your-diff-api-key>"

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [otlphttp]
    metrics:
      receivers: [otlp]
      exporters: [otlphttp]
    logs:
      receivers: [otlp]
      exporters: [otlphttp]

You can add processors for filtering, redaction, or sampling between the receiver and exporter as needed.

Rollout steps

1. Pick a collector strategy from the options above.
2. Configure each coding agent to emit OTLP (see Agent Configuration below).
3. Send a test session and verify it appears in Diff before rolling out broadly.

Agent Configuration

Each coding agent has its own way of enabling OpenTelemetry export. Below are setup instructions for the most common agents. In all examples, replace the endpoint with your collector address or use otel.getdiff.now for Diff's hosted collector.

Claude Code

Claude Code has native OpenTelemetry support. Enable it with environment variables. See the Claude Code telemetry docs for full details.

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otel.getdiff.now"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <your-diff-api-key>"

For faster testing, you can lower the export interval:

export OTEL_METRIC_EXPORT_INTERVAL=10000
export OTEL_LOGS_EXPORT_INTERVAL=5000

Codex CLI

Codex CLI (OpenAI) supports OpenTelemetry export. Configure it with standard OTel environment variables. See the Codex CLI repository for the latest configuration options.

export OTEL_EXPORTER_OTLP_ENDPOINT="https://otel.getdiff.now"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <your-diff-api-key>"

Copilot CLI

GitHub Copilot CLI supports OpenTelemetry export. See GitHub Copilot docs for the latest configuration options.

export OTEL_EXPORTER_OTLP_ENDPOINT="https://otel.getdiff.now"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <your-diff-api-key>"

Gemini CLI

Gemini CLI has native OpenTelemetry support with both gRPC and HTTP protocols. See the Gemini CLI telemetry docs for full details.

export GEMINI_TELEMETRY_ENABLED=true
export GEMINI_TELEMETRY_OTLP_ENDPOINT="https://otel.getdiff.now"
export GEMINI_TELEMETRY_OTLP_PROTOCOL="http"

Or configure via .gemini/settings.json:

{
  "telemetry": {
    "enabled": true,
    "otlpEndpoint": "https://otel.getdiff.now",
    "otlpProtocol": "http"
  }
}

OpenClaw

OpenClaw supports OTLP export via its diagnostics-otel plugin using HTTP/protobuf. See the OpenClaw logging docs for full details.

1. Enable the plugin

openclaw plugins enable diagnostics-otel

2. Configure the endpoint

Either set environment variables:

export OTEL_EXPORTER_OTLP_ENDPOINT="https://otel.getdiff.now"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"

Or configure via ~/.openclaw/openclaw.json:

{
  "diagnostics": {
    "enabled": true,
    "otel": {
      "enabled": true,
      "endpoint": "https://otel.getdiff.now"
    }
  }
}

Note: OpenClaw currently supports HTTP/protobuf only (gRPC is not supported).

Other agents

Any coding agent that emits OTLP can send data to Diff. Point the agent's OTLP exporter at your collector or at otel.getdiff.now directly. If the agent doesn't support OTLP natively, use the Diff CLI as a fallback.