Claude Code tracing not working after setup

Applies to:

Plan -
Deployment -

This article applies to trace-claude-code versions before v2.0.1, including v2.0.0. For v2.0.1 and later, see Claude Code troubleshooting. If you’re upgrading from an older plugin, see Migrate from an older plugin version.

Summary

Issue: Claude Code tracing appears to succeed but logs never appear in Braintrust, and ~/.claude/state/braintrust_hook.log is never created. Cause: The trace-claude-code plugin is not installed or not registered. The braintrust plugin, which lets Claude Code query Braintrust data, is separate and does not register tracing hooks. Resolution: Install the trace-claude-code plugin and verify hooks are registered before testing tracing.

Resolution steps

Step 1: Distinguish the two plugins

Two separate plugins exist:

braintrust: lets you query Braintrust from within Claude Code.
trace-claude-code: registers the hooks that send Claude Code sessions to Braintrust Logs.

Both can be installed simultaneously. Missing logs means trace-claude-code is not loaded.

Step 2: Check which plugins are installed

Exit any running Claude Code session and run from your terminal:

claude plugin list

If trace-claude-code is not listed, install it:

claude plugin install trace-claude-code@braintrust-claude-plugin

Installing from an updated marketplace may install trace-claude-code v2.0.1 or later. In that case, follow the current Claude Code setup guide instead of the environment-variable steps below.

Step 3: Verify hooks are registered

Fully restart Claude Code, then run /hooks inside a session. Confirm trace-claude-code appears with source: Plugin and includes the core tracing hooks, such as:

SessionStart
UserPromptSubmit
PostToolUse
Stop
SessionEnd

In v2.0.0, you may see additional hooks. If the trace-claude-code hooks are missing, the plugin is not loaded and tracing will not work regardless of environment variables.

Step 4: Confirm environment variables are set

echo $TRACE_TO_BRAINTRUST   # must be: true
echo $BRAINTRUST_API_KEY    # must be non-empty
echo $BRAINTRUST_CC_PROJECT # must match your target project name

Set any missing values and fully restart Claude Code after changing them.

Step 5: Enable debug mode and test

Start a fresh session with debug enabled:

TRACE_TO_BRAINTRUST=true \
BRAINTRUST_CC_DEBUG=true \
BRAINTRUST_CC_PROJECT="your-project-name" \
claude --debug-file /tmp/claude-hooks-debug.log

Send one prompt, then exit. Check for hook activity:

tail -n 100 ~/.claude/state/braintrust_hook.log
tail -n 200 /tmp/claude-hooks-debug.log

If braintrust_hook.log still does not exist after this step, the hooks are not executing. Review the debug file for errors about skipped or failed hook commands.

Step 6: View logs in the correct URL

The setup helper may print an incomplete URL. Use the correct pattern to find your logs:

https://www.braintrust.dev/app/{org}/p/{project}/logs

Example:

https://www.braintrust.dev/app/Augment/p/LLM-Coding-Logs/logs

​Summary

​Resolution steps

​Step 1: Distinguish the two plugins

​Step 2: Check which plugins are installed

​Step 3: Verify hooks are registered

​Step 4: Confirm environment variables are set

​Step 5: Enable debug mode and test

​Step 6: View logs in the correct URL

Summary

Resolution steps

Step 1: Distinguish the two plugins

Step 2: Check which plugins are installed

Step 3: Verify hooks are registered

Step 4: Confirm environment variables are set

Step 5: Enable debug mode and test

Step 6: View logs in the correct URL