Track ClaudeClaudeAnthropic’s family of AI models. TelemHQ can track Claude jobs by recording model names, token usage, latency, cost, and run metadata.View glossary entrySource: Anthropic model docs Code With Hooks

When To Use This

Use the Claude Code hook setup when you want to understand local coding-agentagentAn AI application that uses a model, instructions, state, and tools to work toward a goal. Agents are useful to monitor because they can run for a while and make multiple tool calls.View glossary entrySource: Google Cloud Generative AI glossary activity across projects or teams. Use the Claude API guide instead when your own app calls AnthropicAnthropicThe company behind Claude, a family of AI models used for chat, coding, analysis, and tool-using workflows.View glossary entrySource: Anthropic model docs Messages or Message BatchesbatchA group of records or tasks processed together. Batch jobs are often monitored by counting processed items, failed items, duration, and cost.View glossary entrySource: Anthropic API overview directly.

Create an ad hocad hoc jobA task that runs whenever needed instead of on a fixed schedule. TelemHQ records each run but does not fail the tracker just because no scheduled ping arrived.View glossary entrySource: AWS EventBridge Scheduler docs trackertrackerA monitored job, AI pipeline, worker, script, or automation in TelemHQ. Each tracker has its own ping URL and run history.View glossary entrySource: TelemHQ docs with no schedule for normal Claude Code usage. Add a schedule only if the hook runs from a predictable automation, such as a nightly Claude Code job.

1. Save Your PingpingA request sent to TelemHQ after a job runs. A ping can be a simple heartbeat or include JSON payload data about what happened.View glossary entrySource: TelemHQ docs URL

Copy the ping URL from a TelemHQ tracker and make it available to the Claude Code process.

mkdir -p ~/.claude/hooks
chmod 700 ~/.claude/hooks
export TELEMHQ_PING_URL="https://telemhq.com/ping/YOUR_TRACKING_TOKEN"

If Claude Code starts outside this shell, put the environment variable in the shell profile or process manager that launches Claude Code.

2. Add The Hook Script

Save this as ~/.claude/hooks/telemhq_ping.py. It sends metadata only: event name, project, sessionsessionServer-side or cookie-backed state that remembers a signed-in user between requests.View glossary entrySource: MDN glossary id, tool name, and hashed paths. It does not send prompts, commands, file contents, or Claude output.

#!/usr/bin/env python3
import hashlib
import json
import os
import sys
import urllib.request
from pathlib import Path

FAILED_EVENTS = {"PostToolUseFailure", "StopFailure"}


def short_hash(value):
    if not value:
        return None
    return hashlib.sha256(value.encode("utf-8")).hexdigest()[:12]


def compact_payload(payload):
    return {key: value for key, value in payload.items() if value is not None}


def main():
    ping_url = os.environ["TELEMHQ_PING_URL"]
    event = json.load(sys.stdin)

    cwd = event.get("cwd") or os.getcwd()
    hook_event = event.get("hook_event_name", "ClaudeCode")
    last_message = event.get("last_assistant_message")

    payload = compact_payload({
        "provider": "anthropic",
        "tool": "claude-code",
        "status": "failed" if hook_event in FAILED_EVENTS or event.get("error") else "success",
        "event": hook_event,
        "project": Path(cwd).name or "unknown",
        "session_id": event.get("session_id"),
        "tool_name": event.get("tool_name"),
        "tool_use_id": event.get("tool_use_id"),
        "permission_mode": event.get("permission_mode"),
        "cwd_hash": short_hash(cwd),
        "transcript_path_hash": short_hash(event.get("transcript_path")),
        "error": event.get("error"),
        "last_assistant_message_chars": len(last_message) if isinstance(last_message, str) else None,
    })

    request = urllib.request.Request(
        ping_url,
        data=json.dumps(payload).encode("utf-8"),
        headers={"Content-Type": "application/json"},
        method="POST",
    )

    with urllib.request.urlopen(request, timeout=10) as response:
        if response.status >= 300:
            raise RuntimeError(f"TelemHQ returned HTTP {response.status}")


if __name__ == "__main__":
    try:
        main()
    except Exception as exc:
        if os.getenv("TELEMHQ_HOOK_DEBUG") == "1":
            print(f"TelemHQ hook skipped: {exc}", file=sys.stderr)
        sys.exit(0)

chmod 700 ~/.claude/hooks/telemhq_ping.py

3. Configure Claude Code

Add this to ~/.claude/settings.json for all projects, or to .claude/settings.json in one repo. Stop records one ping after each completed turn. StopFailure records API or turn failures.

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/telemhq_ping.py"
          }
        ]
      }
    ],
    "StopFailure": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/telemhq_ping.py"
          }
        ]
      }
    ]
  }
}

Optional Tool Activity

Add this if you also want a ping after successful file edits and shell commands. This creates more pings, but gives project managers a clearer view of which kinds of Claude Code work are happening.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash|Edit|MultiEdit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/telemhq_ping.py"
          }
        ]
      }
    ],
    "PostToolUseFailure": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/telemhq_ping.py"
          }
        ]
      }
    ]
  }
}