How to Track Claude Code Tool Activity with Claude HUD Statusline

Mar 21, 2026

When I’m working with Claude Code on complex tasks, I often find myself wondering: what is it actually doing right now? I see the prompt I sent, and eventually I’ll see the response, but in between? It’s a black box.

Is it reading files? Which ones? How many searches is it running? Did that edit command actually fire?

This lack of visibility bothered me enough to dig into Claude HUD’s tool activity tracking. Here’s what I found.

The Visibility Problem

Claude Code operates with impressive autonomy. You give it a task, and it goes off and does things—reads files, searches codebases, runs commands, edits code. But you don’t see any of that happen in real-time.

I’d ask Claude to refactor a module, and then… wait. Is it stuck? Is it searching? Did it find what it needed? I had no idea until the final response appeared.

What I wanted was a simple answer to “what tools is Claude using right now?”

How Tool Activity Works

Claude HUD solves this by parsing the transcript JSONL file that Claude Code generates during operation. Every tool use gets logged there:

tool_use blocks capture when a tool starts (name, input, timestamp)
tool_result blocks capture when it completes

The HUD reads this file, matches up the starts with the completions, and displays:

Running tools: ◐ spinner with tool name and target file
Completed tools: ✓ with aggregated counts

◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2

The display updates every ~300ms as the HUD re-renders.

Enabling Tool Activity

I enabled it through the configuration command:

/claude-hud:configure

Then selected “Tools activity” from the options. Alternatively, you can edit the config file directly:

{
  "display": {
    "showTools": true
  }
}

What You Actually See

Let me show you what the display looks like in different states.

When a tool is running:

◐ Edit: auth.ts

When tools have completed:

✓ Read ×3 | ✓ Grep ×2 | ✓ Bash ×1

Mixed state (one running, others completed):

◐ Edit: config.ts | ✓ Read ×5 | ✓ Grep ×3

The aggregation is smart—multiple Read operations get grouped into ×5 rather than showing five separate entries. This keeps the statusline clean even during heavy activity.

Supported Tools

The tracking covers all the core Claude Code tools:

File operations: Read, Write, Edit
Search: Grep, Glob
Execution: Bash commands
Subagents: Agent launches
Task tracking: TodoWrite updates

Why This Matters

Real-time tool visibility changes how I work with Claude Code. Instead of wondering “what’s taking so long?”, I can see it’s running a comprehensive search across the codebase. When debugging, I can verify which files Claude actually examined versus which ones it should have looked at.

It’s a simple feature, but it makes the AI’s behavior transparent and debuggable. That matters when you’re trusting an AI with production code.

Under the Hood

For those curious about implementation, here’s the type definition that drives the display:

export interface ToolEntry {
  id: string;
  name: string;
  target?: string;
  status: 'running' | 'completed' | 'error';
  startTime: Date;
  endTime?: Date;
}

The HUD extracts tool_use blocks from the JSONL transcript, matches them with corresponding tool_result blocks, and determines status based on whether the result exists. Running tools simply haven’t received their result yet.

Wrap-up

Tool activity tracking in Claude HUD gives you X-ray vision into Claude Code’s operations. Enable it once, and you’ll always know what files are being read, what searches are running, and what commands are executing—all in real-time on your statusline.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 Claude HUD GitHub

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!