Skip to main content
Applies to:
  • Plan -
  • Deployment -

​
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 (for querying Braintrust from Claude Code) is a separate plugin 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

​
Step 3: Verify hooks are registered

Fully restart Claude Code, then run /hooks inside a session. Confirm trace-claude-code appears with all five hooks and source: Plugin:
  • SessionStart
  • UserPromptSubmit
  • PostToolUse
  • Stop
  • SessionEnd
If these 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