trace-claude-code
starsforks
How to install trace-claude-code?
parcadei/continuous-claude-v3/trace-claude-code
$npx -y skills add parcadei/Continuous-Claude-v3 --skill trace-claude-codeAutomatically trace Claude Code conversations to Braintrust for observability. Captures sessions, conversation turns, and tool calls as hierarchical traces.
SKILL.md
| 1 | # Trace Claude Code to Braintrust |
| 2 | |
| 3 | 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. |
| 4 | |
| 5 | ## What you get |
| 6 | |
| 7 | ``` |
| 8 | Claude Code Session (root trace) |
| 9 | ├── Turn 1: "Add error handling" |
| 10 | │ ├── Read: src/app.ts |
| 11 | │ ├── Edit: src/app.ts |
| 12 | │ └── Response: "I've added try-catch..." |
| 13 | ├── Turn 2: "Now run the tests" |
| 14 | │ ├── Terminal: npm test |
| 15 | │ └── Response: "All tests pass..." |
| 16 | └── Turn 3: "Great, commit this" |
| 17 | ├── Terminal: git add . |
| 18 | ├── Terminal: git commit -m "..." |
| 19 | └── Response: "Changes committed..." |
| 20 | ``` |
| 21 | |
| 22 | ## How it works |
| 23 | |
| 24 | Four hooks capture the complete workflow: |
| 25 | |
| 26 | | Hook | What it captures | |
| 27 | |------|------------------| |
| 28 | | **SessionStart** | Creates root trace when you start Claude Code | |
| 29 | | **PostToolUse** | Captures every tool call (file reads, edits, terminal commands) | |
| 30 | | **Stop** | Captures conversation turns (your message + Claude's response) | |
| 31 | | **SessionEnd** | Logs session summary when you exit | |
| 32 | |
| 33 | ## Quick setup |
| 34 | |
| 35 | Run the setup script in any project directory where you want tracing: |
| 36 | |
| 37 | ```bash |
| 38 | bash /path/to/skills/trace-claude-code/setup.sh |
| 39 | ``` |
| 40 | |
| 41 | The script prompts for your API key and project name, then configures all hooks automatically. |
| 42 | |
| 43 | ## Manual setup |
| 44 | |
| 45 | ### Prerequisites |
| 46 | |
| 47 | - [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed |
| 48 | - [Braintrust API key](https://www.braintrust.dev/app/settings/api-keys) |
| 49 | - `jq` command-line tool (`brew install jq` on macOS) |
| 50 | |
| 51 | ### Configuration |
| 52 | |
| 53 | Create `.claude/settings.local.json` in your project directory: |
| 54 | |
| 55 | ```json |
| 56 | { |
| 57 | "hooks": { |
| 58 | "SessionStart": [ |
| 59 | { |
| 60 | "hooks": [ |
| 61 | { |
| 62 | "type": "command", |
| 63 | "command": "bash /path/to/hooks/session_start.sh" |
| 64 | } |
| 65 | ] |
| 66 | } |
| 67 | ], |
| 68 | "PostToolUse": [ |
| 69 | { |
| 70 | "matcher": "*", |
| 71 | "hooks": [ |
| 72 | { |
| 73 | "type": "command", |
| 74 | "command": "bash /path/to/hooks/post_tool_use.sh" |
| 75 | } |
| 76 | ] |
| 77 | } |
| 78 | ], |
| 79 | "Stop": [ |
| 80 | { |
| 81 | "hooks": [ |
| 82 | { |
| 83 | "type": "command", |
| 84 | "command": "bash /path/to/hooks/stop_hook.sh" |
| 85 | } |
| 86 | ] |
| 87 | } |
| 88 | ], |
| 89 | "SessionEnd": [ |
| 90 | { |
| 91 | "hooks": [ |
| 92 | { |
| 93 | "type": "command", |
| 94 | "command": "bash /path/to/hooks/session_end.sh" |
| 95 | } |
| 96 | ] |
| 97 | } |
| 98 | ] |
| 99 | }, |
| 100 | "env": { |
| 101 | "TRACE_TO_BRAINTRUST": "true", |
| 102 | "BRAINTRUST_API_KEY": "sk-...", |
| 103 | "BRAINTRUST_CC_PROJECT": "my-project" |
| 104 | } |
| 105 | } |
| 106 | ``` |
| 107 | |
| 108 | Replace `/path/to/hooks/` with the actual path to this skill's hooks directory. |
| 109 | |
| 110 | ### Environment variables |
| 111 | |
| 112 | | Variable | Required | Description | |
| 113 | |----------|----------|-------------| |
| 114 | | `TRACE_TO_BRAINTRUST` | Yes | Set to `"true"` to enable tracing | |
| 115 | | `BRAINTRUST_API_KEY` | Yes | Your Braintrust API key | |
| 116 | | `BRAINTRUST_CC_PROJECT` | No | Project name (default: `claude-code`) | |
| 117 | | `BRAINTRUST_CC_DEBUG` | No | Set to `"true"` for verbose logging | |
| 118 | |
| 119 | ## Viewing traces |
| 120 | |
| 121 | After running Claude Code with tracing enabled: |
| 122 | |
| 123 | 1. Go to [braintrust.dev](https://www.braintrust.dev) |
| 124 | 2. Navigate to your project (e.g., `claude-code`) |
| 125 | 3. Click **Logs** to see all traced sessions |
| 126 | |
| 127 | Each trace shows: |
| 128 | - **Session root**: The overall Claude Code session |
| 129 | - **Turns**: Each conversation exchange (user input → assistant response) |
| 130 | - **Tool calls**: Individual operations (file reads, edits, terminal commands) |
| 131 | |
| 132 | ## Trace structure |
| 133 | |
| 134 | Traces are hierarchical: |
| 135 | |
| 136 | - **Session** (root span) |
| 137 | - `span_attributes.type`: `"task"` |
| 138 | - `metadata.session_id`: Unique session identifier |
| 139 | - `metadata.workspace`: Project directory |
| 140 | |
| 141 | - **Turn** (child of session) |
| 142 | - `span_attributes.type`: `"llm"` |
| 143 | - `input`: User message |
| 144 | - `output`: Assistant response |
| 145 | - `metadata.turn_number`: Sequential turn number |
| 146 | |
| 147 | - **Tool call** (child of turn or session) |
| 148 | - `span_attributes.type`: `"tool"` |
| 149 | - `input`: Tool input (file path, command, etc.) |
| 150 | - `output`: Tool result |
| 151 | - `metadata.tool_name`: Name of the tool used |
| 152 | |
| 153 | ## Troubleshooting |
| 154 | |
| 155 | ### No traces appearing |
| 156 | |
| 157 | 1. **Check hooks are running:** |
| 158 | ```bash |
| 159 | tail -f ~/.claude/state/braintrust_hook.log |
| 160 | ``` |
| 161 | |
| 162 | 2. **Verify environment variables** in `.claude/settings.local.json`: |
| 163 | - `TRACE_TO_BRAINTRUST` must be `"true"` |
| 164 | - `BRAINTRUST_API_KEY` must be valid |
| 165 | |
| 166 | 3. **Enable debug mode:** |
| 167 | ```json |
| 168 | { |
| 169 | "env": { |
| 170 | "BRAINTRUST_CC_DEBUG": "true" |
| 171 | } |
| 172 | } |
| 173 | ``` |
| 174 | |
| 175 | ### Permission errors |
| 176 | |
| 177 | Make hook scripts executable: |
| 178 | |
| 179 | ```bash |
| 180 | chmod +x /path/to/hooks/*.sh |
| 181 | ``` |
| 182 | |
| 183 | ### Missing jq command |
| 184 | |
| 185 | Install jq: |
| 186 | - **macOS**: `brew install jq` |
| 187 | - **Ubuntu/Debian**: `sudo apt-get install jq` |
| 188 | |
| 189 | ### State issues |
| 190 | |
| 191 | Reset the tracing state: |
| 192 | |
| 193 | ```bash |
| 194 | rm ~/.claude/state/braintrust_state.json |
People who liked this also viewed
6 picksType
- azure-diagnosticsDebug Azure production issues on Azure using AppLens, Azure Monitor, resource health, and safe triage. WHEN: debug production issues, troubleshoot app service, app service high CPU, app service deploySkillsJul 2026
- systematic-debuggingUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesSkillsJul 2026
- safe-debugRigor Debug / Rigor Audit skill for deep learning research work. Use when the user pastes a traceback, terminal error, CUDA OOM, checkpoint load failure, shape mismatch, NaN loss symptom, or training SkillsMay 2026
- explore-runRigor Improve / Rigor Explore run leaf skill for bounded exploratory evidence in deep learning research repositories. Use when the researcher explicitly authorizes exploratory runs such as small-subseSkillsMay 2026
- minimal-run-and-auditRigor Run skill for README-first deep learning repo reproduction. Use when the task is specifically to capture or normalize evidence from the selected smoke test or documented inference or evaluation SkillsMay 2026
- insforge-debugUse when diagnosing problems in an InsForge project — reactive failures (SDK error object, HTTP 4xx/5xx, gateway timeout 502/503/504, edge function failure or timeout, login/OAuth/auth errors, RLS denSkillsJul 2026
