Background: how usage data flows
Unbound captures Claude Code usage in one of two modes:
The hook lives at
~/.claude/hooks/unbound.py for individual installs. For MDM-deployed installs it lives under the platform’s Claude Code managed directory — /Library/Application Support/ClaudeCode on macOS, /etc/claude-code on Linux, %ProgramFiles%\ClaudeCode on Windows — wired via that directory’s managed settings. On Windows the install prefers a managed-settings.d\unbound.json drop-in so it does not clobber an administrator’s own policy, so check the drop-in as well as managed-settings.json. Check 1.2 detects which one you have. This page covers Claude Code; Cursor, Codex, and Copilot use similar but separate wiring, so for those tools gather the equivalent evidence and contact support.
Four facts explain most “no data” cases:
- Telemetry delivery fails open, by design. Your team’s coding flow comes first: if the hook can’t deliver usage data, Claude keeps working normally and the hook records the error in a local log (plus a rate-limited report to Unbound when the network allows). The flip side of that guarantee: “Claude works fine but no data in Unbound” means a delivery problem, not proof things are okay. The hook keeps the last 25 errors in
~/.claude/hooks/error.log, so check 1.6 is where a delivery problem shows up. Policy enforcement is separate: when the policy engine is unreachable, your org’s failure setting decides whether tool calls are allowed (the default) or blocked, and a blocked call is told “The organization policy engine could not be reached.” - Restart Claude Code after every fix, and prove the restart took. Fully quit it, relaunch from a new terminal, send one prompt, then re-run check 1.6: an
agent-audit.logentry timestamped after the relaunch is the evidence that the configuration now on disk is the one being used. Until you see that entry, treat the fix as unverified. unbound statusconfirms login and connectivity;unbound doctorchecks the hook wiring.statusverifies your credentials, role, and that the Unbound API is reachable.unbound doctorgoes a layer deeper: per tool it verifies the config, the hook script, and the env wiring (and validates your API key), reporting each as healthy / tampered / not set up / managed by MDM. Run it first — it does in one command what checks 1.2 and 1.3 below do by hand. It does not read the local hook logs, so check 1.6 is still yours to run.- Your company may manage Claude Code centrally as well. Settings can reach the machine from your company’s Claude admin console or as a device policy file from IT, in files outside your home directory. When one of those carries a hook restriction, an install that passes every check above still produces nothing, and it produces it silently:
agent-audit.logstays empty anderror.loggains no entry. Check 1.9 reads those files and tells you in seconds.
Phase 1: gather state (read-only)
Run every block and save the outputs.1.0 Which mode is this machine in?
GATEWAY, stop here: checks 1.2 to 1.9 and the decision table apply to subscription mode only. On a gateway machine, “no data” usually means the routing env var or the app key, not hooks; gather 1.1 and 1.7 and go to Phase 5.
1.1 CLI status
Logged in Yes, your work email, your org name, and API status Connected.
If it shows Logged in No, keep gathering — the hook authenticates with its own stored key (check 1.4), so a logged-out CLI alone does not stop telemetry. It does mean the Fix 2 install step will open a browser to authenticate, and if check 1.4 also comes back empty, the stored credential is gone with the login (row D5).
1.2 Hook wiring in settings.json (the most important check)
~/.claude/settings.json) or an MDM-managed one (managed-settings.json); MDM-managed wiring is intentionally outside the user’s home directory.
1.3 Hook script present and executable
x permission bits (e.g. -rwxr-xr-x). It is normal for the other paths to be absent — one per platform, matching the managed directories check 1.2 scans. The explicit FAIL line (or a missing file at the locus 1.2 named) is a D1 signal; if 1.2 found no wiring either, both checks point at the same absent install.
1.4 API key resolvable
~/.unbound/config.json, so an unset env var alone is fine. One ownership detail: the ls -l line should show your username as the owner. If it shows root, the file was written by a setup command run under sudo from this account, and the hook — which runs as you — cannot read it; decision row D5 covers this. (The individual setup is designed to run without sudo; only the MDM fleet flow uses it.)
1.5 Gateway-mode residue (matters if you are in subscription mode)
1.6 Local hook logs (did the hook ever run, and did sends fail?)
error.log: occasional Exception in main: [Errno 32] Broken pipe entries are benign (Claude closed the pipe after the hook already sent its data), and sporadic Hook API error: Command '...' timed out after 20 seconds entries are transient network or gateway latency. On their own, neither indicates broken telemetry. The signals that matter are API request failed and Exception in send_to_api entries timestamped after your recent activity; entries older than your last successful usage are history, not the current fault. Hook API error: entries belong to the policy-check path, not telemetry delivery, and do not explain missing usage data. A Failed to read config file: [Errno 13] Permission denied entry means the hook ran but could not read its credential — match it against check 1.4’s ownership line and treat it as D5. And if the audit log shows recent activity while 1.2/1.3 FAIL, that is not a contradiction: the entries predate whatever removed the wiring or script — still D1.
1.7 Network reachability
000, or TLS errors mean a network/proxy block.
The second URL is the real one: unbound setup and unbound nuke fetch each tool’s installer from raw.githubusercontent.com and run it locally, so that host has to be reachable for any of Phase 3 to work. (getunbound.ai/setup/... is a different channel — the curl-piped installer admins paste into MDM, covered in the admin section at the end.)
1.8 Live end-to-end telemetry test (sends one labeled synthetic event)
This sends one synthetic usage event through the real delivery pipeline. It appears in your org’s Unbound dashboard as a zero-token claude-code event whose prompt starts with[unbound-diagnostic]; if this passes, Phase 4 has a guaranteed event to look for. Run it while no other Claude Code conversation is mid-prompt on this machine, and note that it appends two entries to the local audit log.
API request failed or Exception in send_to_api line timestamped after the test. The hook always exits 0, so the exit code is not a signal; silence in error.log after a real send attempt means the gateway accepted the event.
FAIL: a new API request failed: curl: (7) or curl: (28) line means network egress to Unbound is blocked (Fix 4); a curl: (56) ... 401 or curl: (22) ... 401 line means the key was rejected (Fix 2).
1.9 Organization-managed Claude policy settings (read-only)
Two files on the machine can carry settings your organization set rather than you:~/.claude/remote-settings.json, where settings from your company’s Claude admin console land, and a device policy file installed by IT/MDM at the platform path. The block below reads both and reports whether either carries a disableAllHooks or an allowManagedHooksOnly entry. Those are the two entries a hook restriction is written with, and if one is there the next move is with whoever set it (Fix 5), not with this machine. Reading one of these files by hand, look in two places: allowManagedHooksOnly lives inside the permissions object, disableAllHooks at the top level.
PASS. A FAIL here is the explanation for a machine where everything else passes — including 1.8, where you run the hook script directly, so it passes whether or not the coding tool is running it. The decision table still applies top-down: if D1 also matched (broken wiring and a restriction present), repair the wiring with Fix 2 first, then re-run Phase 1 — this row will still be here.
Reading the output: the presence of a file is not the signal, the restriction keys are. A file reported present with restrictions=None carries neither key and is not a finding — an empty or placeholder policy file is a normal thing to have on a machine. If ~/.claude/remote-settings.json is reported absent, do not conclude anything yet: start one Claude Code session, send a prompt, quit, and re-run this check. If it is still absent after that, there is no cloud policy file here for D2 to match on.
Two cross-checks, both for the human at the keyboard:
- In an interactive Claude Code session, run
/statusand read out the configuration sources it lists. Slash commands are not available to shell-driven agents (claude -p "/status"reports them unavailable) — an agent should ask the human for this rather than attempt it. - Ask which Claude account and organization this machine is signed into. That is the admin console Fix 5 has you contact, and it is worth establishing before anyone goes looking when more than one workspace is in play.
Phase 2: decision table
Match your Phase 1 results top-down; the first matching row is your diagnosis.Phase 3: fix ladder
Start at the fix your decision row names; move further down the ladder only if Phase 4 still fails after it.Agents: tiers 1 and 2 are safe to run. Tier 3 (
nuke) removes Unbound from every AI tool on the machine, so confirm with the human before running it. Fix 5 changes nothing locally — it is a coordination step with the organization’s Claude admin; prepare the message, let the human send it.Fix 1: restart properly
Agents: restarting Claude Code ends your own session. Before handing this step to the user, write a resume file at
~/unbound-diagnosis.md containing your Phase 1 outputs, the decision row you matched, and any fix already applied, then tell the user: after relaunching, point the new session at this page and say “resume from ~/unbound-diagnosis.md”.1
Fully quit Claude Code
Close every session, tab, and window, not just the conversation.
2
Open a brand-new terminal
So refreshed environment variables load.
3
Relaunch Claude Code from that terminal, then send one prompt
Now check
~/.claude/hooks/agent-audit.log for an entry timestamped after the relaunch. That entry is the restart working; no entry means it did not.Fix 2: clean re-install
--clear needs no login at all, and the install command reuses your stored unbound login credential from ~/.unbound/config.json when check 1.4 found one. If 1.4 came back empty — or you have never logged in — the install command opens a browser to authenticate, so have your Unbound login ready. Notes:
- Precondition: both 1.7 checks must PASS before running
--clear. Both commands download each tool’s installer before doing anything, so on a blocked network the clear is a no-op that removes nothing — but a network that drops between the two commands leaves the machine cleared and not reinstalled. Resolve D7 first, and run the pair back to back. - If check 1.4 reported the config file unreadable (owner
root): restore ownership first withsudo chown $(id -un) ~/.unbound/config.json, then run the clear/install pair. This state appears when a setup command was previously run withsudofrom this account; run the individual setup withoutsudogoing forward. - The clear step removes Unbound config for every tool it can manage (both Claude Code and Codex modes, Cursor, Copilot, Augment, Pi, and Gemini CLI); the install step then sets up the five default tools (Claude Code, Cursor, Codex, Copilot, Augment). That is intentional: it removes cross-mode and cross-tool residue in one pass. If you use Gemini CLI or Pi through Unbound, re-run their setup afterwards with
unbound setup gemini-cli/unbound setup pi. - Every tool must show a green check and the run must end with
All tools configured. If any tool fails, do not proceed; check 1.7 (network) and retry, on a different network if needed. - Optional: add
--backfillto the install command to also upload local session history and fill the data gap from the outage. - Re-run check 1.2. If any event still FAILs after a successful run, go to Fix 3.
- Then do Fix 1 (restart). Always.
Fix 3: nuke and repave
Use when Fix 2 reports success but checks still fail, or when mode-switch residue keeps coming back:nuke also deletes the stored login (~/.unbound/config.json), so the follow-up setup will ask you to authenticate in a browser; on a remote or headless machine, plan for that before nuking. If check 1.2 still reports hook entries after a clear or nuke, they name a path the cleaner was not looking at — typically a stale ~/.claude path left behind after CLAUDE_CONFIG_DIR changed. Remove those from settings.json by hand, or escalate (Phase 5).
Then either run the Fix 2 install command again (unbound setup --all), or re-onboard everything (all tools plus device discovery) with the onboard command from the Configure page (gateway.getunbound.ai/configure → My device).
Then Fix 1 (restart). Re-run all of Phase 1.
Fix 4: delivery blocked (hook fires, sends fail)
1
Re-check network reachability
Re-run 1.7. If
api.getunbound.ai is unreachable, you are behind a corporate proxy or firewall. Ask IT to allow api.getunbound.ai (and backend.getunbound.ai), or test on another network to confirm.2
Refresh credentials
If reachable but error.log shows auth-style failures: run Fix 2 to refresh the key, then Fix 1.
Fix 5: align with your organization’s Claude policy
Nothing on this machine needs repair; this is a coordination step. Checks 1.2 to 1.8 already passed, so re-running setup would rewrite configuration that is already correct and leave check 1.6 exactly as empty as it is now.1
Identify the policy source from check 1.9
cloud policy means it is set in your company’s Claude admin console; device policy means your IT/MDM team ships it to the machine.2
Loop in the owning admin
Two clean resolutions, in order of preference: (a) the admin adds the Unbound hooks block to the managed settings themselves, so the hooks ride the policy channel that already wins precedence (contact us for the exact JSON for your org); (b) the admin relaxes the restriction (
allowManagedHooksOnly / disableAllHooks) for your org or fleet.To date the policy for the admin, use the two clocks on the machine: ls -l the file check 1.9 found, and take the last entry in ~/.claude/hooks/agent-audit.log before the data went quiet. A policy file written around the time the audit log stops is the change to ask about.3
Restart and verify
After the admin-side change, do Fix 1, re-run check 1.9 — it should now PASS, or show the Unbound hooks inside the policy — then Phase 4.
Phase 4: verify it actually works
1
Start a NEW Claude Code session
After fixing and restarting, run two or three real prompts.
2
Check the local evidence
3
Check the Unbound dashboard
Your session should appear at gateway.getunbound.ai, usually within a minute. Wait five minutes before treating this step as failed. Check Logs for this, not the analytics breakdowns — those can lag hours behind Logs without anything being wrong.
Phase 5: escalate to Unbound support
If Phase 4 fails after the fix ladder, every check this page can make has passed on the machine — and we want to hear from you. Compile this bundle:- Full output of all Phase 1 checks
- The exact tier(s) of Phase 3 you ran and their console output
unbound --versionand your OS version- The timeframe of the missing data and the affected user emails (this is support’s first question; including it saves a round trip)
Agents: do not send this bundle anywhere on your own. Compile it, confirm it is redacted, present it to the user, and end with an open question, for example: “Your diagnostic bundle is ready and sanitized. How would you like to send it: should I draft an email to support@unboundsecurity.ai for your review, or would you rather send it yourself?” The user decides where escalation goes; you prepare it.
A note on switching modes
Switching modes (gateway → subscription or back) swaps one delivery pipeline for the other. If the switch was interrupted partway (a blocked download on a corporate network, for example), settings from both modes can linger together and data stops flowing. If your data stopped right when you switched, go straight to Fix 2 (clean re-install), or Fix 3 (nuke) if anything survives it. The switch also changes which organization policies matter. Gateway mode does not use hooks, so a Claude policy restricting them (check 1.9) can sit on a machine or org indefinitely without any visible effect — until the switch to subscription mode, at which point telemetry goes quiet from the first session. “Data stopped exactly when we switched” therefore does not imply something changed at that moment: run 1.9 before concluding the switch itself misfired, and if it FAILs, go to Fix 5 — re-running setup (Fix 2/3) will not change the outcome.For admins: MDM / fleet rollouts
- A device appearing in Discovery (inventory of installed AI tools) does not mean coding telemetry is flowing — discovery and governance are installed separately. Verify a fleet rollout by checking that usage events arrive; usage events are the ground truth, and dashboard fields that lag a successful install should not be treated as failure signals.
- MDM-pushed setup (
sudo unbound onboard) installs system-level hooks that need sudo to tamper with. On MDM devices the hook wiring lives in/Library/Application Support/ClaudeCode/managed-settings.json, not the user’s home; checks 1.2 and 1.3 detect this automatically, and the per-user checks (1.4 to 1.6) still apply per home directory. See MDM Integrations. - Success criterion for a fleet push: every target device produces at least one usage event within 24 hours of a developer using a wired tool. Devices that check in but never produce usage are exactly the failure mode this page diagnoses.
- If your organization manages Claude Code settings from the Claude admin console, a
disableAllHooksorallowManagedHooksOnlyentry in that policy reaches every device the policy covers, so one console change can take a whole fleet’s hook telemetry out at once. Two fleet patterns point here: usage that went quiet at the same moment a Claude policy shipped, and — easier to miss — a fleet that switched from gateway to subscription mode and never produced hook telemetry at all. Gateway mode does not use hooks, so a restriction can predate the switch by months without a single symptom. In both cases check 1.9 on any one affected device confirms it in seconds, and Fix 5 describes the two resolutions. We can provide the exact hooks JSON for your console policy on request.

