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-codeInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
AutomationSupported Platforms
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.
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 foundOur 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.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| trace-claude-code (this skill)by parcadei | 89 | 3.9k | 10mo ago | SKILL.md |
| Agent-Reachby Panniantong | 100 | 112.3k | 8d ago | CLAUDE.md |
| rufloby ruvnet | 100 | 81.9k | today | CLAUDE.md |
| Claude-Code-Game-Studiosby Donchitos | 100 | 39.7k | 7d ago | CLAUDE.md |
| Scraplingby D4Vinci | 100 | 103.6k | 2d ago | MCP 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.
Skill content
View source on GitHubname: 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
- Claude Code CLI installed
- Braintrust API key
jqcommand-line tool (brew install jqon macOS)
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:
- Go to braintrust.dev
- Navigate to your project (e.g.,
claude-code) - 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 identifiermetadata.workspace: Project directory
-
Turn (child of session)
span_attributes.type:"llm"input: User messageoutput: Assistant responsemetadata.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 resultmetadata.tool_name: Name of the tool used
Troubleshooting
No traces appearing
-
Check hooks are running:
tail -f ~/.claude/state/braintrust_hook.log -
Verify environment variables in
.claude/settings.local.json:TRACE_TO_BRAINTRUSTmust be"true"BRAINTRUST_API_KEYmust be valid
-
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
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
ruflo
81.9k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
Claude-Code-Game-Studios
39.7kTurn Claude Code into a full game dev studio — 49 AI agents, 72 workflow skills, and a complete coordination system mirroring real studio hierarchy.
Scrapling
103.6k🕷️ The BEST Web Scraping framework that handles everything from a single request to a full-scale crawl! Don't be shy, join here: https://discord.gg/EMgGbDceNQ and follow here for daily tips and tricks: https://x.com/Scrapling_dev
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
