agenttrace Session Audit
Use this skill when session logs need an operational read: spend, token burn, cache use, tool failures, retry loops, latency, health, anomalies, and CI gate readiness.
Workflow
- Prefer the installed
agenttrace binary when it is available on PATH.
- If the binary is not available and the current directory is the
luoyuctl/agenttrace repository, use cargo run -q -p agenttrace --.
- Start with discovery unless the user gave a specific file or directory:
agenttrace --doctor
agenttrace --overview
- For a fast human report, use Markdown:
agenttrace --overview -f markdown -o agenttrace-overview.md
- For automation or CI, use JSON or health gates:
agenttrace --overview -f json -o agenttrace-overview.json
agenttrace --overview --fail-under-health 80 --fail-on-critical --max-tool-fail-rate 15
- For a single recent session:
agenttrace --latest
agenttrace --latest -f json
- For a specific export or session directory:
agenttrace path/to/session-or-export.json
agenttrace --overview -d path/to/session-dir
Report Focus
- Lead with the highest-risk sessions and the reason they matter.
- Call out token/cost waste, repeated tool failures, retry loops, long gaps, and low health scores.
- When proposing a CI gate, include the exact
agenttrace command and threshold.
- If no sessions are detected, run
agenttrace --doctor and report the detected agent directories and next step.
- Report the session capability level (
Detailed, Aggregate, or Limited) before relying on latency or step evidence.
- Treat Tool Steps as metadata-only evidence. Do not imply that Aggregate or Limited sources have a complete execution trace.
Guardrails
- Treat prompts, code, and session contents as local/private data. Do not upload logs to external services.
- Do not invent metrics. If a parser cannot infer cost, model, or latency, say which field is missing.
- Do not compare missing event-level evidence as zero latency or zero failures; mark it unavailable.
- Do not overwrite user reports unless the user asked for that output path.
1---
2name: agenttrace-session-audit
3description: Audit local AI coding-agent sessions with agenttrace for cost, tokens, tool failures, latency, anomalies, health, diffs, and CI gates.
4category: observability
5license: MIT
6requires:
7 bins: [agenttrace]
8---
9
10# agenttrace Session Audit
11
12Use this skill when session logs need an operational read: spend, token burn, cache use, tool failures, retry loops, latency, health, anomalies, and CI gate readiness.
13
14## Workflow
15
161. Prefer the installed `agenttrace` binary when it is available on `PATH`.
172. If the binary is not available and the current directory is the `luoyuctl/agenttrace` repository, use `cargo run -q -p agenttrace --`.
183. Start with discovery unless the user gave a specific file or directory:
19
20```bash
21agenttrace --doctor
22agenttrace --overview
23```
24
254. For a fast human report, use Markdown:
26
27```bash
28agenttrace --overview -f markdown -o agenttrace-overview.md
29```
30
315. For automation or CI, use JSON or health gates:
32
33```bash
34agenttrace --overview -f json -o agenttrace-overview.json
35agenttrace --overview --fail-under-health 80 --fail-on-critical --max-tool-fail-rate 15
36```
37
386. For a single recent session:
39
40```bash
41agenttrace --latest
42agenttrace --latest -f json
43```
44
457. For a specific export or session directory:
46
47```bash
48agenttrace path/to/session-or-export.json
49agenttrace --overview -d path/to/session-dir
50```
51
52## Report Focus
53
54- Lead with the highest-risk sessions and the reason they matter.
55- Call out token/cost waste, repeated tool failures, retry loops, long gaps, and low health scores.
56- When proposing a CI gate, include the exact `agenttrace` command and threshold.
57- If no sessions are detected, run `agenttrace --doctor` and report the detected agent directories and next step.
58- Report the session capability level (`Detailed`, `Aggregate`, or `Limited`) before relying on latency or step evidence.
59- Treat Tool Steps as metadata-only evidence. Do not imply that Aggregate or Limited sources have a complete execution trace.
60
61## Guardrails
62
63- Treat prompts, code, and session contents as local/private data. Do not upload logs to external services.
64- Do not invent metrics. If a parser cannot infer cost, model, or latency, say which field is missing.
65- Do not compare missing event-level evidence as zero latency or zero failures; mark it unavailable.
66- Do not overwrite user reports unless the user asked for that output path.
gabrielmoreira