bashkit-debug

The BashKit Debug Trace Analyzer is a specialized diagnostic utility designed for developers building agentic coding tools with the BashKit framework. By processing JSONL-formatted debug files generated during agent runs, this skill provides visibility into the internal lifecycle of tool executions, including start-to-end correlation, nested parent/child task relationships, and precise timing metrics. It is an essential tool for engineers who need to understand why an agent stalled, why a specific tool returned an error, or how to optimize complex multi-step workflows. The analyzer parses tool-specific summary fields from bash, read, write, edit, glob, grep, task, and web-based operations to offer a comprehensive diagnostic breakdown.

• Automatically correlates tool call events using unique ID tracking to link start, end, and error signals.

• Calculates latency and duration for every tool invocation, highlighting slow operations that exceed performance thresholds.

• Aggregates error statistics and identifies failure patterns such as recurring bash exit codes, failed file reads, or regex mismatches in grep operations.

• Visualizes sub-agent task hierarchies by mapping parent/child relationships in multi-agent execution flows.

• Provides a step-by-step analysis playbook to evaluate agent behavior, detect infinite loops, and verify tool parameter inputs and outputs.

• Uses BASHKIT_DEBUG=file:/path/to/trace.jsonl as the standard input format for logs.

• Includes a helper script for terminal-based summarization of large trace files to identify trends without manual file inspection.

• Ideal for debugging Vercel AI SDK integrations, local sandbox environments, and Vercel remote sandbox deployments.

• Supports analyzing complex nested sub-agent interactions and token usage reporting within task tools.

• Effective for troubleshooting file system errors like 'string not found' during edit operations or 'exit code 1' failures in bash command execution.