Start from one Claude Code task and keep the task identifier stable
Choose a bounded repository task and record the Claude command you would normally run. Keep the repository revision, Claude version, and task prompt available for the investigation. This makes the resulting process tree and file scope easier to interpret and gives you something reproducible if a runtime or tracing change affects capture.
Use Claude Code telemetry for the semantics it already exposes
Current Claude Code OpenTelemetry can report API requests, tool result events, permission decisions, MCP activity, skills, cost and token metrics, and optional traces. Detailed flags can include Bash commands, MCP server/tool names, and tool arguments. Those events are usually the best source for why Claude selected a tool or whether a permission was accepted.
Use AgentSight when execution leaves the native telemetry boundary
A Bash tool can start package managers, compilers, tests, browsers, language servers, or other descendants. AgentSight adds process, path, network, and resource observations around that execution. Claude's own docs explicitly note that its OTEL_* variables are not passed to Bash subprocesses, hooks, MCP servers, or language servers, which is a concrete reason the parent trace does not automatically become a full distributed trace of every child.
Know the current Claude TLS compatibility path
AgentSight v1.0.3 documents Claude Code as a Bun-based application with statically linked, stripped BoringSSL. The TLS tracer therefore cannot rely on a system libssl path and exported SSL_read/SSL_write symbols. AgentSight uses validated byte-pattern discovery for supported builds and also avoids a comm filter on the SSL side because traffic can execute on an internal HTTP Client thread rather than the main claude thread.
Investigate the same time range in semantic and system views
When a tool looks slow, compare the Claude tool event duration with the child process and resource timeline. When a file or network effect looks unexpected, return to the corresponding Claude tool call and permission decision. The goal is a joined explanation: the native trace supplies intent and policy; the system trace supplies independently observed execution.
Treat detailed telemetry and plaintext capture as sensitive
Claude's optional telemetry flags can include prompts, tool inputs, tool content, or raw API bodies, while AgentSight TLS/session capture can contain similarly sensitive material. Enabling both can duplicate secrets and source content into different storage systems. Use the minimum content flags needed for the investigation and keep raw local AgentSight sessions under the same handling rules as other sensitive developer telemetry.
$ sudo agentsight record -- claude
$ agentsight report serve
$ sudo agentsight debug ssl --binary-path <claude-binary> --verbose