Usage Not Showing Up

​

Background: how usage data flows

1. 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. Non-blocking hook errors don’t appear in the Claude UI (only a hook exiting with code 2 surfaces to the model). To watch hooks execute live, run claude --debug or toggle verbose output with Ctrl+O; the local logs in check 1.6 give you the full history. 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 blocked calls show an explicit “policy engine could not be reached” message.
2. Hooks load only at Claude startup. Claude Code reads its hook configuration once, when a session starts. After any fix, fully quit Claude Code and relaunch it from a new terminal so the fresh configuration loads.
3. unbound status confirms login and connectivity; unbound doctor checks the hook wiring. status verifies your credentials, role, and that the Unbound API is reachable. unbound doctor goes 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.6 below do by hand.
4. Organization-managed Claude settings outrank local ones. Claude Code applies settings from several scopes, and organization-managed scopes — delivered from your company’s Claude admin console, or as a device policy file from IT — take precedence over ~/.claude/settings.json. A policy that restricts hooks turns an otherwise healthy individual install silent: no error log, no warning, nothing in --debug. Check 1.9 detects this in seconds.

​

Phase 1: gather state (read-only)

​

1.0 Which mode is this machine in?

python3 - <<'EOF'
import json, os
helper = False
try:
    helper = 'apiKeyHelper' in json.load(open(os.path.expanduser('~/.claude/settings.json')))
except Exception:
    pass
base = bool(os.environ.get('ANTHROPIC_BASE_URL'))
print('mode: GATEWAY' if (helper or base) else 'mode: SUBSCRIPTION (hooks)')
EOF

​

1.1 CLI status

unbound status

​

1.2 Hook wiring in settings.json (the most important check)

python3 - <<'EOF'
import json, os
paths = [os.path.expanduser('~/.claude/settings.json'),
         '/Library/Application Support/ClaudeCode/managed-settings.json']
expected = ['PreToolUse','PostToolUse','UserPromptSubmit','Stop','SessionStart','SessionEnd']
found = False
for p in paths:
    if not os.path.exists(p):
        continue
    try:
        s = json.load(open(p))
    except json.JSONDecodeError as e:
        print(f'FAIL {p} is malformed JSON: {e}')
        continue
    hooks = s.get('hooks') or {}
    if 'unbound.py' not in json.dumps(hooks):
        continue
    found = True
    print(f'install locus: {p}')
    for ev in expected:
        cmds = [h.get('command','') for grp in hooks.get(ev, []) for h in grp.get('hooks', [])]
        print(f"{'PASS' if any('unbound.py' in c for c in cmds) else 'FAIL'} hook event {ev}")
    break
if not found:
    print('FAIL no Unbound hooks wired in user or managed settings')
try:
    user = json.load(open(os.path.expanduser('~/.claude/settings.json')))
    print(f"{'FAIL' if 'apiKeyHelper' in user else 'PASS'} apiKeyHelper absent (must be absent in subscription mode)")
except Exception:
    print('PASS apiKeyHelper absent (no user settings.json)')
EOF

​

1.3 Hook script present and executable

FOUND=0
for p in ~/.claude/hooks/unbound.py "/Library/Application Support/ClaudeCode/hooks/unbound.py"; do
  [ -f "$p" ] && { ls -l "$p"; FOUND=1; }
done
[ "$FOUND" = "1" ] || echo "FAIL hook script absent at both locations"

​

1.4 API key resolvable

[ -n "$UNBOUND_CLAUDE_API_KEY" ] && echo "env: <set>" || echo "env: <unset>"
ls -l ~/.unbound/config.json 2>/dev/null
python3 - <<'EOF'
import json, os
p = os.path.expanduser('~/.unbound/config.json')
try:
    key = json.load(open(p)).get('api_key')
    print('config.json key:', 'present' if key else 'MISSING')
except FileNotFoundError:
    print('config.json key: MISSING (file not found)')
except PermissionError:
    print('config.json key: UNREADABLE (permission denied; check the ls -l owner above)')
except json.JSONDecodeError:
    print('config.json key: MISSING (file is malformed JSON)')
EOF

​

1.5 Gateway-mode residue (matters if you are in subscription mode)

echo "ANTHROPIC_BASE_URL: ${ANTHROPIC_BASE_URL:-<unset>}"
[ -n "$UNBOUND_API_KEY" ] && echo "UNBOUND_API_KEY: <set>" || echo "UNBOUND_API_KEY: <unset>"
ls ~/.claude/anthropic_key.sh 2>/dev/null && echo "FAIL gateway key helper still present" || echo "PASS no gateway key helper"
cat ~/.zshrc ~/.zprofile ~/.bashrc ~/.bash_profile 2>/dev/null | grep -nE '^[[:space:]]*(export[[:space:]]+)?(ANTHROPIC_BASE_URL|UNBOUND_API_KEY)=' | sed -E 's/=.*/=<redacted>/' | grep . || echo "PASS no gateway exports in rc files"

​

1.6 Local hook logs (did the hook ever run, and did sends fail?)

ls -la ~/.claude/hooks/
[ -f ~/.claude/hooks/error.log ] && sed -E 's/Bearer [A-Za-z0-9._-]+/Bearer [REDACTED]/g' ~/.claude/hooks/error.log | tail -20 || echo "no error.log (hook has never logged an error, or never ran)"
python3 - <<'EOF'
import json, os
p = os.path.expanduser('~/.claude/hooks/agent-audit.log')
try:
    lines = open(p).read().splitlines()[-5:]
except FileNotFoundError:
    print('no agent-audit.log (hook has likely never executed)')
    raise SystemExit
for ln in lines:
    try:
        e = json.loads(ln)
        print(e.get('timestamp', '?'), e.get('event', {}).get('hook_event_name', '?'))
    except Exception:
        print('(unparseable line)')
EOF

​

1.7 Network reachability

curl -sS --max-time 15 -o /dev/null -w "unbound ingest: HTTP %{http_code}\n" -X POST https://api.getunbound.ai/v1/hooks/claude
curl -sS --max-time 15 -o /dev/null -w "github raw (setup dependency): HTTP %{http_code}\n" https://raw.githubusercontent.com/websentry-ai/setup/refs/heads/main/claude-code/hooks/unbound.py

​

1.8 Live end-to-end telemetry test (sends one labeled synthetic event)

HOOK="$HOME/.claude/hooks/unbound.py"
[ -f "$HOOK" ] || HOOK="/Library/Application Support/ClaudeCode/hooks/unbound.py"
[ -f "$HOOK" ] || { echo "FAIL hook script not found at either location (go to Fix 2)"; exit 1; }
SID="unbound-diag-$(date +%s)"
echo "{\"hook_event_name\":\"UserPromptSubmit\",\"session_id\":\"$SID\",\"prompt\":\"[unbound-diagnostic] telemetry self-test, please ignore\"}" | python3 "$HOOK"
echo "{\"hook_event_name\":\"Stop\",\"session_id\":\"$SID\",\"last_assistant_message\":\"[unbound-diagnostic] synthetic reply\"}" | python3 "$HOOK"
sleep 1; tail -3 ~/.claude/hooks/error.log 2>/dev/null || echo "no error.log"

​

1.9 Organization-managed Claude policy settings (read-only)

python3 - <<'EOF'
import json, os
paths = [
    (os.path.expanduser('~/.claude/remote-settings.json'), 'cloud policy (set in your Claude admin console)'),
    ('/Library/Application Support/ClaudeCode/managed-settings.json', 'device policy (macOS)'),
    ('/etc/claude-code/managed-settings.json', 'device policy (Linux)'),
]
flagged = False
cloud_active = False
for i, (p, label) in enumerate(paths):
    is_cloud = i == 0
    if not os.path.exists(p):
        print(f'absent   {label}')
        continue
    try:
        s = json.load(open(p))
    except Exception as e:
        print(f'present  {label}: unreadable or malformed ({e})')
        continue
    keys = {k: s[k] for k in ('disableAllHooks', 'allowManagedHooksOnly') if k in s}
    wired = 'unbound.py' in json.dumps(s.get('hooks') or {})
    if is_cloud and isinstance(s, dict) and s:
        cloud_active = True
    line = f'present  {label}: restrictions={keys or None} unbound_hooks_inside={"yes" if wired else "no"}'
    if not is_cloud and cloud_active:
        print(line + ' (not consulted: a non-empty cloud policy takes precedence)')
        continue
    print(line)
    if keys.get('disableAllHooks') or (keys.get('allowManagedHooksOnly') and not wired):
        flagged = True
print('FAIL hook-restricting policy is active (decision row D2)' if flagged else 'PASS no policy blocks the Unbound hook')
EOF

• Human-only: in an interactive Claude Code session, /status includes a Setting sources line listing every configuration scope that loaded. An Enterprise managed settings entry marked (remote) means cloud policies are active on this machine; a file-based entry points at the device policy. Slash commands are not available to shell-driven agents (claude -p "/status" reports them unavailable) — agents should ask the human to read this line out, not attempt it.
• Shell-safe: claude auth status --json shows which Claude account, organization, and plan the machine is signed into — cloud policies follow the signed-in organization, so this tells you exactly whose admin console to ask about when more than one workspace is in play.

​

Phase 2: decision table

​

Phase 3: fix ladder

​

Fix 1: restart properly

​

Fix 2: clean re-install

unbound setup --all --clear     # removes every tool's Unbound config (both modes)
unbound setup --all             # reinstalls Unbound config for Cursor, Claude Code, Codex, Copilot, Augment

• Precondition: both 1.7 checks must PASS before running --clear. The clear happens first; if the network can’t reach GitHub raw, the reinstall fails and the machine ends up with no Unbound config at all. Resolve D7 first.
• If check 1.4 reported the config file unreadable (owner root): restore ownership first with sudo chown $(id -un) ~/.unbound/config.json, then run the clear/install pair. This state appears when a setup command was previously run with sudo from this account; run the individual setup without sudo going forward.
• The clear step removes Unbound config for every tool it can manage (both Claude Code and Codex modes, Cursor, Copilot, Augment, 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 through Unbound, re-run its setup afterwards with unbound setup gemini-cli.
• 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 --backfill to 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

unbound nuke          # removes Unbound from every tool, user-level (asks to confirm)
# sudo unbound nuke   # use instead if your install was MDM/system-level

​

Fix 4: delivery blocked (hook fires, sends fail)

​

Fix 5: align with your organization’s Claude policy

​

Phase 4: verify it actually works

tail -5 ~/.claude/hooks/agent-audit.log    # should show entries from the last few minutes
tail -5 ~/.claude/hooks/error.log 2>/dev/null   # should show NO new "API request failed"

​

Phase 5: escalate to Unbound support

1. Full output of all Phase 1 checks
2. The exact tier(s) of Phase 3 you ran and their console output
3. unbound --version and your OS version
4. The timeframe of the missing data and the affected user emails (this is support’s first question; including it saves a round trip)

sed -E 's/Bearer [A-Za-z0-9._-]+/Bearer [REDACTED]/g' ~/.claude/hooks/error.log

​

A note on switching modes

​

For admins: MDM / fleet rollouts

• A device appearing in Discovery (inventory of installed AI tools) does not mean coding telemetry is flowing. Discovery and telemetry are separate pipelines with separate keys. 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, two properties matter for telemetry: those settings replace the device policy file rather than merging with it, and disableAllHooks / allowManagedHooksOnly apply fleet-wide to every individually-installed hook. 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.