SkillAgentSearch skills...

trace-claude-code

Automatically trace Claude Code conversations to Braintrust for observability. Captures sessions, conversation turns, and tool calls as hierarchical traces.

Install / Use

npx skills add parcadei/Continuous-Claude-v3 --skill trace-claude-code

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

89/100

Category

Automation

Supported Platforms

Claude Code

Our assessment of trace-claude-code

trace-claude-code scores 89/100 on our quality scale, 1345th of 2,790 Automation skills we index (top 49%).

Its SKILL.md is 5.9 KB long, well organised into 21 sections with 8 code examples: a thorough specification that gives an agent plenty to work with.

With 3,943 GitHub stars, it is one of the more widely adopted skills in the catalogue.

Substance
29/30
Structure
20/20
Description
15/15
Adoption
15/20
Freshness
11/15

Maintenance, license and trust

  • The repository was last updated about 10 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.
  • Our last check on 2026-10-31 found the source still online.
  • It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
  • Its trust signals score 94/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-10-01. Automated pattern scan on 2026-09-30. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

trace-claude-code compared with similar skills

All 4 of these similar skills score higher than trace-claude-code; compare them before choosing.

SkillScoreStarsUpdatedFormat
trace-claude-code (this skill)by parcadei893.9k10mo agoSKILL.md
Agent-Reachby Panniantong100112.3k8d agoCLAUDE.md
rufloby ruvnet10081.9ktodayCLAUDE.md
Claude-Code-Game-Studiosby Donchitos10039.7k7d agoCLAUDE.md
Scraplingby D4Vinci100103.6k2d agoMCP Server

Frequently asked questions

How do I install trace-claude-code?
Run npx skills add parcadei/Continuous-Claude-v3 --skill trace-claude-code. The install tabs above show the steps for each supported agent.
Which AI agents does trace-claude-code work with?
It is written for Claude Code, as a SKILL.md file. Other agents that read the same format can often use it too.
Is trace-claude-code safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 94/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is trace-claude-code still maintained?
The repository was last updated about 10 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.

name: trace-claude-code description: | Automatically trace Claude Code conversations to Braintrust for observability. Captures sessions, conversation turns, and tool calls as hierarchical traces. version: 1.1.0

Trace Claude Code to Braintrust

Automatically send Claude Code conversations to Braintrust for tracing and observability. Get full visibility into your AI coding sessions with hierarchical traces showing sessions, turns, and every tool call.

What you get

Claude Code Session (root trace)
├── Turn 1: "Add error handling"
│   ├── Read: src/app.ts
│   ├── Edit: src/app.ts
│   └── Response: "I've added try-catch..."
├── Turn 2: "Now run the tests"
│   ├── Terminal: npm test
│   └── Response: "All tests pass..."
└── Turn 3: "Great, commit this"
    ├── Terminal: git add .
    ├── Terminal: git commit -m "..."
    └── Response: "Changes committed..."

How it works

Four hooks capture the complete workflow:

| Hook | What it captures | |------|------------------| | SessionStart | Creates root trace when you start Claude Code | | PostToolUse | Captures every tool call (file reads, edits, terminal commands) | | Stop | Captures conversation turns (your message + Claude's response) | | SessionEnd | Logs session summary when you exit |

Quick setup

Run the setup script in any project directory where you want tracing:

bash /path/to/skills/trace-claude-code/setup.sh

The script prompts for your API key and project name, then configures all hooks automatically.

Manual setup

Prerequisites

Configuration

Create .claude/settings.local.json in your project directory:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash /path/to/hooks/session_start.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "bash /path/to/hooks/post_tool_use.sh"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash /path/to/hooks/stop_hook.sh"
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash /path/to/hooks/session_end.sh"
          }
        ]
      }
    ]
  },
  "env": {
    "TRACE_TO_BRAINTRUST": "true",
    "BRAINTRUST_API_KEY": "sk-...",
    "BRAINTRUST_CC_PROJECT": "my-project"
  }
}

Replace /path/to/hooks/ with the actual path to this skill's hooks directory.

Environment variables

| Variable | Required | Description | |----------|----------|-------------| | TRACE_TO_BRAINTRUST | Yes | Set to "true" to enable tracing | | BRAINTRUST_API_KEY | Yes | Your Braintrust API key | | BRAINTRUST_CC_PROJECT | No | Project name (default: claude-code) | | BRAINTRUST_CC_DEBUG | No | Set to "true" for verbose logging |

Viewing traces

After running Claude Code with tracing enabled:

  1. Go to braintrust.dev
  2. Navigate to your project (e.g., claude-code)
  3. Click Logs to see all traced sessions

Each trace shows:

  • Session root: The overall Claude Code session
  • Turns: Each conversation exchange (user input → assistant response)
  • Tool calls: Individual operations (file reads, edits, terminal commands)

Trace structure

Traces are hierarchical:

  • Session (root span)

    • span_attributes.type: "task"
    • metadata.session_id: Unique session identifier
    • metadata.workspace: Project directory
  • Turn (child of session)

    • span_attributes.type: "llm"
    • input: User message
    • output: Assistant response
    • metadata.turn_number: Sequential turn number
  • Tool call (child of turn or session)

    • span_attributes.type: "tool"
    • input: Tool input (file path, command, etc.)
    • output: Tool result
    • metadata.tool_name: Name of the tool used

Troubleshooting

No traces appearing

  1. Check hooks are running:

    tail -f ~/.claude/state/braintrust_hook.log
    
  2. Verify environment variables in .claude/settings.local.json:

    • TRACE_TO_BRAINTRUST must be "true"
    • BRAINTRUST_API_KEY must be valid
  3. Enable debug mode:

    {
      "env": {
        "BRAINTRUST_CC_DEBUG": "true"
      }
    }
    

Permission errors

Make hook scripts executable:

chmod +x /path/to/hooks/*.sh

Missing jq command

Install jq:

  • macOS: brew install jq
  • Ubuntu/Debian: sudo apt-get install jq

State issues

Reset the tracing state:

rm ~/.claude/state/braintrust_state.json

Hook logs

View detailed hook execution logs:

# Follow logs in real-time
tail -f ~/.claude/state/braintrust_hook.log

# View last 50 lines
tail -50 ~/.claude/state/braintrust_hook.log

# Clear logs
> ~/.claude/state/braintrust_hook.log

File structure

hooks/
├── common.sh          # Shared utilities (logging, API, state)
├── session_start.sh   # Creates root trace span
├── post_tool_use.sh   # Captures tool calls
├── stop_hook.sh       # Captures conversation turns
└── session_end.sh     # Finalizes trace

Alternative: SDK integration

For programmatic use with the Claude Agent SDK, use the native Braintrust integration:

import { initLogger, wrapClaudeAgentSDK } from "braintrust";
import * as claudeSDK from "@anthropic-ai/claude-agent-sdk";

initLogger({
  projectName: "my-project",
  apiKey: process.env.BRAINTRUST_API_KEY,
});

const { query, tool } = wrapClaudeAgentSDK(claudeSDK);

See Braintrust Claude Agent SDK docs for details.

Related Skills

View on GitHub
GitHub Stars3.9k
CategoryAutomation
Updated9mo ago
Forks303

Languages

Python

Trust signals

94/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

1 low