Span Coding Hooks: IT Admin User Guide for Rippling

This guide covers deploying Span Coding Hooks with Rippling to both macOS and Windows devices. Span ships a native package for each. Step 1 is shared; Steps 2–4 note the macOS and Windows specifics inline.

What This Package Does

Span Coding Hooks captures AI coding activity (prompts, file edits, tool use) from supported IDEs (currently Cursor, Claude Code, Codex CLI, Copilot CLI, and VSCode chat) and sends telemetry to Span's analytics backend. This data appears in your Span dashboard under AI Effectiveness.

Prerequisites

Before deploying, you need:

• A Span account with access to integration settings.

• A Rippling account with Device Management, and target devices enrolled and grouped (Rippling groups can be driven by any employee attribute — department, team, role).

• The release artifact(s) from your Span account team: coding-hooks-{version}.pkg (macOS) and/or coding-hooks-{version}.msi (Windows).

• Each engineer's work email in Rippling — used to identify the individual on their device.

• macOS: devices on macOS 12.0+ enrolled in Rippling.

• Windows: Windows 10/11 devices enrolled in Rippling.

Windows — unsigned installer. The .msi is currently unsigned in all releases, so Windows may show a SmartScreen/Defender prompt and policies that require signed installers will block it. This is temporary and will be resolved shortly (Azure Trusted Signing). Pilot on an allowlisted group, or wait for the signed release, if your policy requires it.

Deployment Steps

The flow is the same on both platforms: deliver a config file with your token and the employee's email, then deploy the package. The config file uses one schema everywhere:

{ "span_auth_token": "<token>", "work_email": "<employee work email>" }

The token is shared org-wide; the work email is per-device.

Step 1: Enable the Integration and Get Your Token (this needs to be done once)

This step is the same regardless of your MDM.

Head to the AI tool settings dashboard (https://span.app/_/settings/integrations) and under IDE & CLI AI Tool Integrations, enable the tools your engineers use. Here is what each tool supports:

Note: The Cursor, Copilot CLI, and VSCode chat integrations do not yet have a toggle in the dashboard. If your engineers use any of these, enable Claude Code or Codex CLI to generate the token — the token is shared across all tools and is required by the package regardless of which IDEs you are deploying for.

Once you enable a tool, you'll be able to access the token that you have to use to authenticate against our Otel backend:

Step 2: Deploy the Span Configuration File via MDM

The token is org-wide; the email is per-device. Deliver both so the config file exists before (or with) the package. Inject the assigned employee's work email into the config script as a Rippling attribute variable.

macOS — write the config from a pre-install script attached to the package (see Step 3), so it lands before the package installs. The script runs as root and writes /Library/Application Support/app.span.coding-hooks/span-config.json (root:staff 0640):

#!/bin/bash
set -euo pipefail
DIR="/Library/Application Support/app.span.coding-hooks"; FILE="$DIR/span-config.json"
TOKEN="__PASTE_SPAN_AUTH_TOKEN__"
EMAIL="__RIPPLING_WORK_EMAIL_VARIABLE__"   # assigned employee's work email — see note
mkdir -p "$DIR"
printf '{\n  "span_auth_token": "%s",\n  "work_email": "%s"\n}\n' "$TOKEN" "$EMAIL" > "$FILE"
chown root:staff "$FILE"; chmod 0640 "$FILE"

Windows — add a PowerShell custom script (Rippling → Devices → Custom Scripts), run as SYSTEM, that writes %ProgramData%\Span\CodingHooks\span-config.json:

$ErrorActionPreference = "Stop"
$Token = "__PASTE_SPAN_AUTH_TOKEN__"
$Email = "__RIPPLING_WORK_EMAIL_VARIABLE__"   # assigned employee's work email — see note
if (-not $Email) { throw "Could not resolve work email." }
$Dir = Join-Path $env:ProgramData "Span\CodingHooks"; New-Item -ItemType Directory -Force $Dir | Out-Null
[pscustomobject]@{ span_auth_token = $Token; work_email = $Email } |
  ConvertTo-Json | Set-Content (Join-Path $Dir "span-config.json") -Encoding utf8

On the work email: replace __RIPPLING_WORK_EMAIL_VARIABLE__ with Rippling's variable for the assigned employee's work email (confirm the exact token in the Rippling script editor); it resolves per-device automatically. Paste your org token in place of __PASTE_SPAN_AUTH_TOKEN__.

Step 3: Deploy the Package

Upload the artifact under Software (app.rippling.com/hardware/software → Upload Software) and assign it to the same devices/group as Step 2.

• macOS: set Operating System to macOS, drop in the .pkg, and attach the Step 2 bash script as the Pre-install script (this guarantees span-config.json exists before the package installs). Submit, then assign to your target devices.

• Windows: set Operating System to Windows, drop in the .msi, and add silent install arguments (/qn /norestart). Assign to the same devices as the Step 2 PowerShell script. On install, the MSI's bundled install.ps1 reads the config and sets up the hooks, the SpanOtelCollector service, and the SpanRegistryPoller task. (Reminder: the MSI is unsigned for now — see the Prerequisites note.)

Rippling doesn't strictly order a standalone custom script against a software install. On macOS the pre-install script removes any ordering concern. On Windows, if the PowerShell config script runs after the MSI, it's still fine: the package tolerates span-config.json arriving around install time and re-reads it on every event — but for a clean first run, set the config script to run at enrollment / on a short recurring schedule.

Step 4: Smoke Test (before fleet rollout)

Assign Steps 2–3 to 1–2 pilot devices first. Confirm the config script and the package both report success in Rippling, then verify on-device (see below) before assigning to the fleet.

Verifying the Deployment

The installer runs a full health check at the end of every install. To verify manually:

macOS

pkgutil --pkg-info app.span.coding-hooks
~/.span/bin/span-health

Windows

Get-Service SpanOtelCollector
& "$env:LOCALAPPDATA\Span\bin\hook-dispatcher.exe" span-health

A healthy check plus the device appearing in your Span dashboard confirms success.

Upgrading

Upload the new artifact version to the existing Software item (and re-attach the macOS pre-install script). Assigned devices reinstall on the next check-in; user IDE configs are preserved.

Uninstalling

Remove the Software item from the target group — Rippling uninstalls it automatically on the next check-in — or run the bundled uninstall script. Removal reverses the service/task and preserves user-defined IDE configurations.

Troubleshooting

Support

For anything not covered here, contact your Span account team with the device OS, the failing step, and the output of span-health.