Finally got observability working for Claude Code: how the hooks actually work

I’ve been daily driving the Claude Code CLI for a bit now. It’s easily the fastest terminal agent I’ve used for refactors, but the one thing driving me crazy was the total lack of visibility. When an agent takes 40 seconds to finish a turn or starts looping on a shell command, I want to know exactly where the bottleneck is—not just wait for the final output. I spent the weekend digging into how to actually trace these sessions. Unlike other tools, Claude Code is a bit of a "post-hoc" system. It doesn't give you real-time event streams out of the box, but it writes every single detail—thinking blocks, tool calls, and exact token usage—into JSONL transcript files on your disk at `~/.claude/projects/{project}/sessions/{session}.jsonl`. To get this into a readable trace, you have to use the `Stop` hook in your `~/.claude/settings.json`. The trick is that this hook fires right after the turn ends, allowing you to run a script that parses the latest transcript and reconstructs the entire hierarchical span. The cool part about Claude Code's model is that it exposes token data that Cursor doesn't. You can see the exact breakdown of prompt tokens vs. cache creation vs. completion tokens. It’s the only way I’ve found to actually track what a session is costing in real-time. My config looks like this now: JSON { "hooks": { "Stop": [ { "hooks": [ { "type": "command", "command": "python ~/.claude/hooks/keywordsai_hook.py" } ] } ] } } Now, instead of just a terminal output, I get a full trace tree that looks like this: * **claude\_session\_xyz** (32.4s) * ├── **Thinking** (1.2s) - "Analyzing the dependency graph..." * ├── **Tool: list\_files** (0.4s) * ├── **Thinking** (0.8s) - "I need to check the test suite." * └── **Shell: npm test** (5.1s) It makes debugging agent failures a lot less like guesswork. If anyone wants the specific Python logic for parsing the JSONL transcripts and pushing them to an API, see my full docs in comments. https://preview.redd.it/hs5astt64edg1.png?width=2287&format=png&auto=webp&s=2fb8d16ad2cd5bf79033cc0890f52ad0e7413cb0