Skip to content
BSWEN
Blog

How to Track Claude Code Subagent Execution and Nested Agent Trees

Cowrie
Cowrie
Dev @ Bswen

I was debugging a multi-agent workflow in Claude Code, and I had no idea what my subagents were actually doing. I’d spin up three parallel agents to review code, check security, and write tests, but when something went wrong, I was flying blind. Which agent failed? Which one consumed all my tokens? What prompts did I actually send them?

The Task tool in Claude Code is powerful for parallel execution, but it creates a black box. Here’s what I saw in my terminal:

Using Task tool for parallel execution...
Task 1: Running code-reviewer agent
Task 2: Running security-checker agent
Task 3: Running test-writer agent


... 47 seconds later ...


All tasks completed.

That’s it. No visibility into what happened inside those agents. No breakdown of costs. No way to see which agent was slow or expensive. This made optimizing my multi-agent architecture feel like trial and error.

Environment

  • Claude Code CLI (latest version)
  • Multi-agent workflows using Task tool
  • Node.js 18+ for devtools installation
  • macOS/Linux terminal

What I Discovered

I found claude-devtools, a tool that gives you full visibility into every subagent execution. It renders each subagent spawned by the Task tool as a complete execution tree showing prompts, tool calls, token usage, cost, and duration.

The Reddit community had been talking about this feature as essential for understanding complex multi-agent systems. When Claude spins up subagents, you can see:

  • Every prompt sent to each subagent
  • All tool calls made by each agent
  • Token usage and cost per agent
  • Execution duration
  • Nested agent hierarchies when agents spawn more agents

The Solution

I installed claude-devtools and pointed it at my Claude Code logs:

Terminal
# Install globally
npm install -g claude-devtools


# Run it
claude-devtools

The tool opened a browser interface showing all my Claude Code sessions. I navigated to a session where I’d used parallel agents, and clicked the “Agents” tab.

Here’s what I saw for a session where I ran three parallel tasks:

Agent Execution Tree
Main Agent (12,450 tokens, $0.45)
├─ Task: code-reviewer (8,200 tokens, $0.28)
│  ├─ Read: auth.ts (320 tokens)
│  ├─ Grep: "security" (180 tokens)
│  └─ Write: review.md (450 tokens)
├─ Task: security-checker (6,100 tokens, $0.21)
│  └─ Read: auth.ts (280 tokens)
│  └─ Grep: "vulnerability|inject" (190 tokens)
└─ Task: test-writer (9,800 tokens, $0.33)
   ├─ Read: auth.ts (320 tokens)
   └─ Write: auth.test.ts (580 tokens)

Suddenly everything was visible. I could see that my test-writer agent was the most expensive at $0.33, while security-checker was cheapest at $0.21. The code-reviewer used the most tokens. This data helped me understand where to optimize.

Why This Works

Claude Code logs all agent interactions to local files. The devtools reads these logs and reconstructs the execution tree. Each time the Task tool spawns a subagent, Claude Code records:

  • The full prompt sent to that subagent
  • Every tool call the subagent makes
  • Token consumption for input and output
  • Timestamps for duration calculation

For nested agents (when a subagent spawns its own subagents), the tool builds a hierarchical tree structure. This is crucial for complex orchestrations:

Nested Agent Tree
Main Agent
├─ orchestrator-agent
│  ├─ research-agent (spawned by orchestrator)
│  │  └─ WebFetch: docs.example.com
│  ├─ writer-agent (spawned by orchestrator)
│  │  └─ Write: output.md
│  └─ reviewer-agent (spawned by orchestrator)
│     └─ Read: output.md

Without this visibility, debugging nested agent failures meant guessing which agent in the chain had issues. Now I can trace the exact execution path.

Common Mistakes I Made

Mistake 1: Assuming deterministic behavior

I thought running the same multi-agent workflow twice would give identical results. But subagents can make different decisions, especially when tools return dynamic content (like web searches). The devtools showed me the actual prompts and responses, revealing where variation occurred.

Mistake 2: Ignoring token costs per agent

Before visibility, I only looked at total session cost. But when I saw the breakdown, I realized one agent type consumed 60% of my tokens. I redesigned that agent to be more efficient.

Mistake 3: Not reviewing agent prompts

After orchestration runs, I’d just check if the output was correct. But reviewing the actual prompts in devtools showed me where my instructions to agents were ambiguous, leading to wasted iterations.

Mistake 4: Over-parallelizing

I assumed more parallel agents meant faster results. The devtools showed me that some agents were waiting on others due to implicit dependencies I hadn’t recognized. I restructured to reduce contention.

The Task tool isn’t the only way to spawn agents in Claude Code. Team features like TeamCreate and SendMessage also create agent instances. The devtools shows these as color-coded cards, making it easy to track which teammate is doing what.

Understanding execution trees also helps with:

  • Cost optimization: Identify expensive agents and optimize their prompts or reduce their usage
  • Performance tuning: Find slow agents and investigate why (too many tool calls? slow API responses?)
  • Failure debugging: When an orchestration fails, trace exactly which agent and which tool call caused the issue
  • Architecture design: See how agents interact and redesign for better flow

The visibility also revealed something unexpected: some of my agents were calling tools I hadn’t intended. A code review agent was making file writes when I only wanted it to read and comment. Without devtools, I wouldn’t have caught this.

Summary

In this post, I showed how claude-devtools gives you complete visibility into Claude Code’s multi-agent execution. The key points:

  • Install with npm install -g claude-devtools
  • Each subagent appears as a detailed card with full execution tree
  • See prompts, tool calls, tokens, cost, and duration per agent
  • Nested agents display as hierarchical trees
  • Use this data to optimize costs, debug failures, and improve architecture

Multi-agent systems are becoming essential for complex AI workflows. Without visibility tools, you’re working in the dark. With claude-devtools, every decision your agents make becomes transparent and measurable.

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:

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

Comments

Tags: