agenttrace-session-audit
Audit local AI coding-agent sessions with agenttrace for cost, tool failures, latency, anomalies, health, diffs, and CI gates.
- License 许可
- MIT
- 所属仓库
- ASoudy/AGS
- 最近更新
- 2026-05-23
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- agenttrace-session-audit
- risk
- safe
- tags
- [ "ai-coding", "observability", "cost-tracking", "session-analysis" ]
- tools
- [ "claude", "cursor", "gemini", "codex-cli" ]
- author
- luoyuctl
- source
- community
- license
- MIT
- category
- development
- date_added
- 2026-05-10
- description
- Audit local AI coding-agent sessions with agenttrace for cost, tool failures, latency, anomalies, health, diffs, and CI gates.
- source_repo
- luoyuctl/agenttrace
- source_type
- community
- license_source
- https://github.com/luoyuctl/agenttrace/blob/master/LICENSE
03 SKILL.md 正文
agenttrace Session Audit
Overview
Use this skill to inspect local AI coding-agent sessions with agenttrace. It focuses on the process behind a run: token and cost spikes, tool failures, retry loops, latency gaps, anomalies, health scores, and session-to-session diffs.
agenttrace is local-first and reads session logs from tools such as Claude Code, Codex CLI, Gemini CLI, Aider, Cursor exports, OpenCode, Qwen Code, Kimi, and generic JSON or JSONL traces.
When to Use This Skill
- Use when a user asks why an AI coding run was slow, expensive, shallow, or unreliable.
- Use when reviewing local agent logs before retrying a failed or suspicious task.
- Use when building a lightweight CI health gate for AI-assisted coding sessions.
- Use when comparing two attempts and looking for changed tool paths, retries, or cost patterns.
How It Works
Step 1: Discover Available Sessions
Prefer an installed agenttrace binary when it is available on PATH. If the
current repository is luoyuctl/agenttrace, use go run ./cmd/agenttrace
instead.
agenttrace --doctor
agenttrace --overview
If no sessions are detected, report the directories checked by --doctor and
ask for the exported session file or log directory.
Step 2: Produce a Human-Readable Audit
Use Markdown when the user wants a concise report they can inspect or share.
agenttrace --overview -f markdown -o agenttrace-overview.md
In the report, lead with the highest-risk sessions and explain why they matter: critical anomalies, repeated tool failures, token or cost waste, long latency gaps, low health scores, and suspiciously shallow sessions.
Step 3: Inspect One Session or Directory
Use the latest session for a quick check, or pass an explicit export path when the user provides one.
agenttrace --latest
agenttrace --latest -f json
agenttrace path/to/session-or-export.json
agenttrace --overview -d path/to/session-dir
Step 4: Compare Attempts When Semantics Matter
Token and latency metrics can look healthy even when an agent confidently takes the wrong implementation path. When the risk is semantic drift, pair the trace audit with a diff against a previous or known-good attempt.
Look for:
- changed files or commands that diverge from the intended task
- missing tests or verification steps compared with the reference attempt
- repeated edits around the same files without a clear reason
- lower cost that came from skipping necessary exploration
Step 5: Add Automation Gates
For CI or repeatable team workflows, use JSON output or health thresholds.
agenttrace --overview -f json -o agenttrace-overview.json
agenttrace --overview --fail-under-health 80 --fail-on-critical --max-tool-fail-rate 15
Tune thresholds to the project. A strict gate is useful for critical workflows; a reporting-only command is better while the team is learning its baseline.
Examples
Quick Local Review
agenttrace --overview
agenttrace --latest
Use this after a long coding-agent run to decide whether the next prompt should split the task, avoid a failing tool path, add missing tests, or reset context.
CI Health Check
agenttrace --overview --fail-under-health 80 --fail-on-critical
Use this when agent session logs are available in CI and the team wants a simple guard against critical anomalies or unhealthy runs.
Best Practices
- Start with
--doctorwhen session discovery is uncertain. - Report missing fields plainly; do not invent cost, model, latency, or health data.
- Treat prompts, code, and session contents as private local data.
- Prefer JSON output for automation and Markdown output for human review.
- Use trace metrics for process failures and diff/reference review for semantic drift.
Limitations
- agenttrace can only analyze logs that are present locally or provided as exports.
- Some agents do not expose enough fields to infer cost, model, cache use, or latency.
- Healthy trace metrics do not prove the final code is correct; still run tests and review diffs.
- CI gates should start as advisory until the team understands normal baseline behavior.
Security & Safety Notes
- Do not upload private session logs to external services unless the user explicitly approves it.
- Do not overwrite user reports unless they requested that exact output path.
- Avoid printing secrets found in prompts, tool output, environment variables, or logs.
Common Pitfalls
-
Problem: No sessions are found. Solution: Run
agenttrace --doctor, then point agenttrace at the exported file or log directory. -
Problem: A run looks cheap and fast but produced the wrong refactor. Solution: Compare the session against a prior attempt or known-good diff; cost metrics alone will miss semantic drift.
-
Problem: CI fails too often after adding a health gate. Solution: Start with JSON or Markdown reporting, inspect normal baselines, then tighten thresholds gradually.
Related Skills
@langfuse- Use for production LLM application tracing and evaluation.@observability-engineer- Use for broader service monitoring, SLOs, and incident workflows.
04 同仓库更多 Skills
web-typography
Select, pair, and implement typefaces for web projects. Use when the user mentions "font pairing", "which typeface", "line height", "responsive typography", "web font loading", "type hierarchy", "variable fonts", "FOUT/FOIT", or "typographic scale". Also trigger when choosing between system fonts and web fonts, optimizing font loading performance, or designing readable long-form content layouts. Covers readability evaluation, CSS implementation, and performance optimization. For overall UI design systems, see refactoring-ui. For dramatic typographic experiences, see top-design.
ux-heuristics
Evaluate and improve interface usability using heuristic analysis. Use when the user mentions "usability audit", "UX review", "users are confused", "heuristic evaluation", "form usability", "navigation problems", "Nielsen heuristics", "cognitive walkthrough", or "usability testing". Also trigger when reviewing a design for usability issues, improving form completion rates, or evaluating information architecture and navigation. Covers Nielsens 10 heuristics, severity ratings, and information architecture. For visual design fixes, see refactoring-ui. For conversion-focused audits, see cro-methodology.
traction-eos
Implement the Entrepreneurial Operating System (EOS) to align vision and execution across a company. Use when the user mentions "EOS", "V/TO", "quarterly rocks", "Level 10 meetings", "accountability chart", "IDS process", "Entrepreneurial Operating System", or "business operating system". Also trigger when a growing company needs meeting structure, goal-setting frameworks, or a systematic approach to solving recurring organizational issues. Covers the six EOS components: Vision, People, Data, Issues, Process, Traction. For team motivation design, see drive-motivation. For lean experimentation, see lean-startup.
top-design
Create award-winning, immersive web experiences at the level of Awwwards-featured agencies. Use when the user mentions "premium website", "portfolio site", "scroll animations", "Awwwards quality", "brand experience", "cinematic web design", "parallax storytelling", or "agency-quality site". Also trigger when building landing pages that need to impress, designing creative portfolios, or elevating a standard website to a memorable digital experience. Covers dramatic typography, purposeful motion, scroll-based composition, and performance-optimized animation. For foundational UI, see refactoring-ui. For type selection, see web-typography.
system-design
Design scalable distributed systems using structured approaches for load balancing, caching, database scaling, and message queues. Use when the user mentions "system design", "scale this", "high availability", "rate limiter", "design a URL shortener", "system design interview", "capacity planning", or "distributed architecture". Also trigger when estimating infrastructure requirements, choosing between microservices and monoliths, or designing for millions of concurrent users. Covers common system designs and back-of-the-envelope estimation. For data fundamentals, see ddia-systems. For resilience, see release-it.
storybrand-messaging
Clarify brand messaging using narrative structure that positions the customer as hero. Use when the user mentions "brand message", "website copy", "elevator pitch", "one-liner", "messaging isnt resonating", "brand script", "StoryBrand framework", or "customer as hero". Also trigger when rewriting homepage copy, crafting email nurture sequences, or creating consistent messaging across sales collateral and marketing materials. Covers landing page copy, marketing collateral, and consistent communication. For memorable messaging, see made-to-stick. For product positioning, see obviously-awesome.