Monitor Claude Code with TraceHawk

pip install tracehawk

# .claude/hooks/pre_tool_call.py
"""
TraceHawk hook — traces every tool call Claude Code makes.
Place in your project's .claude/hooks/ directory.
"""
import tracehawk
import json, sys, time

tracehawk.init(api_key="ao-...")

def on_pre_tool_call(event: dict) -> dict:
    """Called before each tool invocation."""
    # event contains: tool_name, tool_input, conversation_id
    event["_th_start"] = time.time()
    return event

def on_post_tool_call(event: dict) -> dict:
    """Called after each tool invocation with result."""
    duration_ms = (time.time() - event.get("_th_start", time.time())) * 1000

    tracehawk.trace_tool_call(
        tool_name=event.get("tool_name"),
        tool_input=event.get("tool_input", {}),
        tool_result=event.get("tool_result", {}),
        duration_ms=duration_ms,
        conversation_id=event.get("conversation_id"),
        error=event.get("error"),
    )
    return event

{
  "hooks": {
    "pre_tool_call": ".claude/hooks/pre_tool_call.py::on_pre_tool_call",
    "post_tool_call": ".claude/hooks/pre_tool_call.py::on_post_tool_call"
  }
}

"""
Alternative: use the Python SDK directly in your agent script.
Works when you control the script that spawns Claude Code programmatically.
"""
import tracehawk
import subprocess

tracehawk.init(api_key="ao-...")

@tracehawk.observe(name="claude-code-session")
def run_agent_task(prompt: str, project_dir: str) -> str:
    """Run a Claude Code task and trace it end-to-end."""
    result = subprocess.run(
        ["claude", "--print", prompt],
        cwd=project_dir,
        capture_output=True,
        text=True,
    )
    return result.stdout

# Run — full session appears as one trace in TraceHawk
output = run_agent_task(
    prompt="Add unit tests for the authentication module",
    project_dir="/path/to/project"
)

# .claude/settings.json — enable TraceHawk MCP server
{
  "mcpServers": {
    "tracehawk": {
      "command": "npx",
      "args": ["-y", "@tracehawk/mcp-observer"],
      "env": {
        "TRACEHAWK_API_KEY": "ao-..."
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_..." }
    }
  }
}

# Every MCP tool call captured as a span:
{
  "span_kind": "MCP",
  "mcp.server_name": "filesystem",
  "mcp.tool_name": "read_file",
  "mcp.tool_input": { "path": "/workspace/src/auth.ts" },
  "duration_ms": 12,
  "status": "ok"
}