auspex: IT Admin User Guide for Microsoft Intune (macOS)

Last updated: August 20, 2026

This guide is for IT administrators deploying the Span agent (auspex) to macOS devices via Microsoft Intune.

What This Package Does

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

The macOS installer is a single universal .pkg. When it installs elevated (as Intune does), it places the binary at /usr/local/bin/auspex, drops a root-owned managed configuration at /Library/Application Support/auspex/ (the managed.yaml marker = managed mode), and converges automatically (postinstall runs auspex install --system, wires machine-wide hooks, provisions each engineer's identity, and starts the per-user agent at login).

You don't need a separate "install hooks" step — the package converges itself. Your job is to (a) pre-authorize file access so users are never prompted, and (b) deliver each device's identity (token + work email) before the package installs.

Prerequisites

  • A Span account with access to integration settings.
  • A Microsoft Intune tenant with target macOS devices (macOS 13+, supervised via ADE/ABM) enrolled and assigned to Entra groups, with the Intune management agent installed.
  • Each engineer's work email populated in Entra (the mail attribute).
  • The macOS package: https://auspex.span.app/releases/v0.1.0/darwin/auspex_0.1.0_darwin_universal.pkg (download and upload it as an app).

Deployment order (important)

  1. Custom configuration profiles (file access + background items, and the email variable) — first.
  2. Shell script that writes identity.json — before/with the package.
  3. The package (line-of-business app, Required).

Step 1: Enable the Integration and Get Your Token (one-time)

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:

Tool What's captured
Claude Code OTEL metrics + hooks
Cursor Hooks
Codex CLI OTEL metrics + hooks
Copilot CLI Hooks
VSCode chat Hooks

If a tool has no dashboard toggle, enable Claude Code or Codex CLI to generate the (org-wide) token.

Step 2: Deploy the File-Access + Background-Items Profile (before the package)

auspex reads the edited file from the git working tree the moment an AI edit fires. For users with repos under a TCC-protected folder (Documents, Desktop, Downloads), that would prompt:

"auspex" would like to access files in your Documents folder.

Deploy the combined profile before the package so no one is prompted. It grants Full Disk Access (PPPC), pre-approves auspex's background items, and silences the background-activity notification.

  1. In Intune: Devices → macOS → Configuration → Create → New Policy → Templates → Custom.
  2. Upload auspex-background-items.mobileconfig as the custom configuration profile (.mobileconfig).
  3. Assign to the target device/user group.

The profile ships with Span's Developer ID team (KNH44SBYN4) and binary path pre-filled. Confirm against a deployed Mac if needed: codesign -dr - /usr/local/bin/auspex.

Requires a supervised device from a trusted MDM (macOS 13+).

Step 3: Deploy the Email Variable Profile

Create a custom configuration profile whose .mobileconfig writes the enrolled user's email into the app.span.auspex managed-preference domain. Use Intune's {{mail}} token so each user's Entra email is substituted per device:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>PayloadType</key><string>Configuration</string>
  <key>PayloadVersion</key><integer>1</integer>
  <key>PayloadIdentifier</key><string>app.span.auspex.email</string>
  <key>PayloadUUID</key><string>REPLACE-WITH-UUID</string>
  <key>PayloadDisplayName</key><string>auspex Email Variable</string>
  <key>PayloadScope</key><string>System</string>
  <key>PayloadContent</key>
  <array>
    <dict>
      <key>PayloadType</key><string>app.span.auspex</string>
      <key>PayloadVersion</key><integer>1</integer>
      <key>PayloadIdentifier</key><string>app.span.auspex.email.inner</string>
      <key>PayloadUUID</key><string>REPLACE-WITH-UUID</string>
      <key>work_email</key><string>{{mail}}</string>
    </dict>
  </array>
</dict>
</plist>

Intune writes this to /Library/Managed Preferences/app.span.auspex.plist. Verify on a test device:

/usr/bin/defaults read "/Library/Managed Preferences/app.span.auspex" work_email

Step 4: Deploy the Identity Script

Add a shell script (Devices → macOS → Scripts → Add), run as root (not the logged-on user), replacing <YOUR_TOKEN> with the token from Step 1:

#!/bin/bash
set -euo pipefail

TOKEN="<YOUR_TOKEN>"
EMAIL="$(/usr/bin/defaults read '/Library/Managed Preferences/app.span.auspex' work_email 2>/dev/null || true)"
if [ -z "$EMAIL" ] || [[ "$EMAIL" != *"@"* ]]; then
  echo "ERROR: work_email not found. Confirm the Step 3 email profile installed and the Entra mail attribute is set." >&2
  exit 1
fi

DIR="/Library/Application Support/auspex"
mkdir -p "$DIR"
printf '{\n  "token": "%s",\n  "work_email": "%s"\n}\n' "$TOKEN" "$EMAIL" > "$DIR/identity.json"
chown root:wheel "$DIR/identity.json"
chmod 644 "$DIR/identity.json"
echo "Success: identity.json written for $EMAIL"

The identity.json is a delivery file the package's converge reads at install time, migrating it into each user's own private (0600) identity and removing it.

Step 5: Deploy the Package

Add the package as a line-of-business app: Apps → All apps → Create → macOS → Line-of-business app, upload the .pkg, set Minimum OS to macOS 13, add a Logo (LOB apps without one don't appear in Company Portal), and assign Required to the same group as Steps 2–4. The .pkg is Developer ID–signed and notarized, satisfying Intune's requirement.

On install, the package converges the device to managed mode and starts the daemon.

Step 6: Smoke Test (before fleet rollout)

Assign Steps 2–5 to 1–2 pilot devices first. Confirm the profiles, script, and app all report success in Intune, then on-device:

/usr/bin/defaults read "/Library/Managed Preferences/app.span.auspex" work_email
pkgutil --pkg-info app.span.auspex
auspex status        # stderr: install mode: managed
auspex auth show     # work email + MASKED token

Then confirm System Settings → Privacy & Security → Full Disk Access shows auspex enabled and "managed by your organization," and that the pilot user's traces appear in the dashboard after using a coding tool.

Optional: Replace legacy Span coding-hooks in the same rollout

If you're migrating from the older coding-hooks agent, you can retire it on each device as part of this rollout. This step is optional and best-effort: it removes coding-hooks only after auspex is confirmed installed, and only if the coding-hooks uninstaller is present — so it's safe to assign fleet-wide, including to devices that never had coding-hooks (there it simply no-ops).

Why bundle it: until coding-hooks is removed, a device running both agents will capture and send each event twice (duplicate traces). Gating removal on a confirmed auspex install lets you cut over cleanly, one device at a time, with no window where neither agent is running.

In Intune: add this as a shell script (Devices → macOS → Scripts), run as root, assigned to the same group. Intune doesn't order scripts against app installs, but the self-gate makes that irrelevant — the script runs at check-in and removes coding-hooks once auspex is confirmed.

#!/bin/bash
# OPTIONAL post-install: retire legacy Span coding-hooks AFTER a confirmed auspex install.
# Safe anywhere — no-ops unless auspex is fully installed, and only removes coding-hooks
# if its uninstaller is present. Never fails the calling MDM step (always exits 0).
set -uo pipefail

CH_UNINSTALL="/Library/Application Support/app.span.coding-hooks/uninstall.sh"

# Gate 1 — auspex package receipt present (install confirmed by macOS).
if ! /usr/sbin/pkgutil --pkg-info app.span.auspex >/dev/null 2>&1; then
  echo "auspex receipt not found — install not confirmed; leaving coding-hooks in place."
  exit 0
fi

# Gate 2 — auspex binary AND managed marker both in place.
if [ ! -x "/usr/local/bin/auspex" ] || [ ! -f "/Library/Application Support/auspex/managed.yaml" ]; then
  echo "auspex not fully in place (binary or managed marker missing) — leaving coding-hooks in place."
  exit 0
fi

# auspex confirmed — best-effort remove coding-hooks, only if its uninstaller exists.
if [ -f "$CH_UNINSTALL" ]; then
  echo "auspex confirmed — removing legacy coding-hooks…"
  bash "$CH_UNINSTALL" || echo "coding-hooks uninstall returned non-zero (best-effort) — continuing."
  echo "Done: coding-hooks removal attempted."
else
  echo "No coding-hooks uninstaller found — nothing to remove."
fi
exit 0

Notes:

  • The script exits 0 on every path, so a coding-hooks removal failure never fails the MDM step or disturbs auspex.
  • It removes coding-hooks only when both auspex gates pass and the uninstaller exists at /Library/Application Support/app.span.coding-hooks/uninstall.sh. On any other device it reports what it skipped and exits cleanly.
  • User-defined hooks in Cursor and Claude Code are preserved by the coding-hooks uninstaller.

Troubleshooting

Symptom Remediation
Config holds a placeholder token Re-run Step 4; confirm the real token is pasted into the script
Missing / wrong work email Populate the Entra mail attribute; confirm the Step 3 profile installed
macOS script never runs Confirm the Intune agent at /Library/Intune/Microsoft Intune Agent.app; user opens Company Portal → Check settings
Managed, but capture unauthenticated Package converged before identity existed — confirm auspex auth show, then re-run sudo auspex install --system
User prompted for Documents access Step 2 profile wasn't in place first — deploy it, then sudo tccutil reset SystemPolicyAllFiles
No data in dashboard Check identity, have the user run a coding tool, confirm the feature is enabled for your org

Upgrading

Upload the new package to the existing LOB app (the app → Properties → App information → Edit → Select file to update). Existing assignments reinstall on next check-in; managed.yaml and edited policy are preserved.

Uninstalling

auspex ships two removers, one per tier. auspex uninstall removes a user-tier (self-installed) agent — its per-user service, binary, and hooks. auspex hooks uninstall --system un-wires the managed (machine-wide) capture hooks. Neither removes the machine-wide binary, launchd units, or root-owned managed config the package placed — a macOS .pkg has no built-in uninstaller and there is no auspex uninstall --system. So a clean managed removal runs both commands, then removes those machine-wide artifacts, then removes the MDM-delivered profiles.

Step 1 — Uninstall auspex

Run it elevated on the device, or deliver it through Intune (as a shell script, run as root). It un-wires the hooks first (while the binary still exists), then removes the daemon units, the managed config, the binary, and the package receipt:

#!/bin/bash
set -uo pipefail
BIN="/usr/local/bin/auspex"   # full path: root/MDM shells often omit /usr/local/bin from PATH

# 1a. Un-wire the MANAGED (machine-wide) capture hooks — the tier the MDM package wired.
"$BIN" hooks uninstall --system || true
# 1b. Clean up any lingering USER-tier install (e.g. a self-install from before the device
#     was enrolled). `auspex uninstall` ONLY touches the per-user tier — it does not remove
#     the managed tier, which is why 1a and the machine-wide removals below are still needed.
"$BIN" uninstall || true

# 2. Stop and remove the launchd units. Boot out the converge LaunchDaemon (system domain) AND
#    the per-user daemon LaunchAgent for every logged-in user (gui/<uid>), then remove the plists.
launchctl bootout system "/Library/LaunchDaemons/app.span.auspex.converge.plist" 2>/dev/null || true
for u in /Users/*; do uid=$(id -u "$(basename "$u")" 2>/dev/null) || continue
  launchctl bootout "gui/$uid" "/Library/LaunchAgents/app.span.auspex.plist" 2>/dev/null || true
done
rm -f "/Library/LaunchDaemons/app.span.auspex.converge.plist" "/Library/LaunchAgents/app.span.auspex.plist"

# 3. Remove the root-owned managed config tree (clear its tamper-proof ACL first).
chmod -N "/Library/Application Support/auspex" 2>/dev/null || true
rm -rf "/Library/Application Support/auspex"

# 4. Remove the binary and forget the package receipt.
rm -f "$BIN"
pkgutil --forget app.span.auspex 2>/dev/null || true

echo "auspex uninstalled"

On a self-installed (non-managed) Mac, auspex uninstall on its own is the complete uninstaller — see the self-install guide. On a managed device it only clears a user-tier remnant, so the managed steps above are still required.

Step 2 — Remove the MDM-delivered profiles and assignment

In Intune, assign the LOB app with the Uninstall intent and unassign the Step 2 profiles, and remove any PayloadRemovalDisallowed lock first. Do this so the MDM does not re-deliver auspex on the next check-in.

Verify the removal is complete

Run on the device — every line should print ok: (no receipt, binary, config, or daemon left):

pkgutil --pkg-info app.span.auspex >/dev/null 2>&1 && echo "STILL PRESENT: package receipt" || echo "ok: no package receipt"
command -v auspex >/dev/null 2>&1 && echo "STILL PRESENT: auspex on PATH ($(command -v auspex))" || echo "ok: auspex not on PATH"
[ -e /usr/local/bin/auspex ] && echo "STILL PRESENT: /usr/local/bin/auspex" || echo "ok: binary gone"
[ -e "/Library/Application Support/auspex" ] && echo "STILL PRESENT: managed config tree" || echo "ok: managed config gone"
launchctl print system/app.span.auspex.converge >/dev/null 2>&1 && echo "STILL LOADED: converge daemon" || echo "ok: converge daemon not loaded"
CU=$(stat -f%u /dev/console 2>/dev/null || echo 0); launchctl print "gui/$CU/app.span.auspex" >/dev/null 2>&1 && echo "STILL LOADED: per-user daemon (gui/$CU)" || echo "ok: per-user daemon not loaded"
ls /Library/LaunchDaemons/app.span.auspex.converge.plist /Library/LaunchAgents/app.span.auspex.plist >/dev/null 2>&1 && echo "STILL PRESENT: launchd units" || echo "ok: launchd units gone"

Fallback — only if the checks above still show remnants

A leftover usually means the tamper-proof ACL blocked removal, a launchd unit was still loaded, or an MDM profile re-pushed the managed config before Step 2 completed. First confirm Step 2 removed the MDM assignment (so nothing re-delivers), then force the removal:

#!/bin/bash
launchctl bootout system "/Library/LaunchDaemons/app.span.auspex.converge.plist" 2>/dev/null || true
# Boot out the per-user daemon agent for every user, best-effort.
for u in /Users/*; do uid=$(id -u "$(basename "$u")" 2>/dev/null) || continue
  launchctl bootout "gui/$uid" "/Library/LaunchAgents/app.span.auspex.plist" 2>/dev/null || true
done
rm -f "/Library/LaunchDaemons/app.span.auspex.converge.plist" "/Library/LaunchAgents/app.span.auspex.plist"
chmod -R -N "/Library/Application Support/auspex" 2>/dev/null || true
rm -rf "/Library/Application Support/auspex"
rm -f /usr/local/bin/auspex
pkgutil --forget app.span.auspex 2>/dev/null || true
echo "auspex force-removed — re-run the verify checks above"

User-defined hooks in Cursor and Claude Code are preserved throughout.

Support

For issues not covered here, contact the Span team with:

auspex status
auspex support        # redacted support bundle