braintrust-analyze
Analyze Claude Code sessions via Braintrust
When & Why to Use This Skill
Braintrust Analysis is a specialized observability tool designed to monitor and evaluate Claude Code sessions. By leveraging Braintrust tracing data, it provides developers with deep insights into agent behavior, tool execution patterns, and resource consumption. This skill is essential for debugging complex AI workflows, detecting execution loops, and optimizing token usage to ensure efficient and cost-effective agent performance.
Use Cases
- Post-Task Retrospectives: Analyze completed complex tasks to understand the agent's decision-making process and identify areas for workflow improvement.
- Loop Detection & Debugging: Automatically detect repetitive tool-call patterns where the agent might be stuck, allowing for faster troubleshooting of inefficient logic.
- Token Usage & Cost Management: Track token consumption trends over daily or weekly periods to monitor API expenses and optimize prompt efficiency.
- Agent & Skill Performance Analytics: Review statistics on which agents (e.g., plan-agent, debug-agent) and skills are most frequently utilized to refine your development environment.
| name | braintrust-analyze |
|---|---|
| description | Analyze Claude Code sessions via Braintrust |
Braintrust Analysis
Analyze your Claude Code sessions for patterns, issues, and insights using Braintrust tracing data.
When to Use
- After completing a complex task (retrospective)
- When debugging why something failed
- Weekly review of productivity patterns
- Finding opportunities to create new skills
- Understanding token usage trends
Commands
Run from the project directory:
# Analyze last session - summary with tool/agent/skill breakdown
uv run python -m runtime.harness scripts/braintrust_analyze.py --last-session
# List recent sessions
uv run python -m runtime.harness scripts/braintrust_analyze.py --sessions 5
# Agent usage statistics (last 7 days)
uv run python -m runtime.harness scripts/braintrust_analyze.py --agent-stats
# Skill usage statistics (last 7 days)
uv run python -m runtime.harness scripts/braintrust_analyze.py --skill-stats
# Detect loops - find repeated tool patterns (>5 same tool calls)
uv run python -m runtime.harness scripts/braintrust_analyze.py --detect-loops
# Replay specific session - show full sequence of actions
uv run python -m runtime.harness scripts/braintrust_analyze.py --replay <session-id>
# Weekly summary - daily activity breakdown
uv run python -m runtime.harness scripts/braintrust_analyze.py --weekly-summary
# Token trends - usage over time
uv run python -m runtime.harness scripts/braintrust_analyze.py --token-trends
Options
--project NAME- Braintrust project name (default: agentica)
What You'll Learn
Session Analysis
- Tool usage breakdown
- Agent spawns (plan-agent, debug-agent, etc.)
- Skill activations (/commit, /research, etc.)
- Token consumption estimates
Loop Detection
Find sessions where the same tool was called repeatedly, which may indicate:
- Stuck in a search loop
- Inefficient approach
- Opportunity for better tooling
Usage Patterns
- Which agents you use most
- Which skills get activated
- Daily/weekly activity trends
Examples
Quick Retrospective
# What happened in my last session?
uv run python -m runtime.harness scripts/braintrust_analyze.py --last-session
Output:
## Session Analysis
**ID:** `92940b91...`
**Started:** 2025-12-24T01:31:05Z
**Spans:** 14
### Tool Usage
- Read: 4
- Bash: 2
- Edit: 2
...
Find Loops
uv run python -m runtime.harness scripts/braintrust_analyze.py --detect-loops
Weekly Review
uv run python -m runtime.harness scripts/braintrust_analyze.py --weekly-summary
Requirements
- BRAINTRUST_API_KEY in ~/.claude/.env or project .env
- Braintrust tracing enabled (via braintrust-claude-plugin)