Skip to main content

Local Telemetry — observe, stats, dashboard

ag-skill ships four commands for recording and reviewing skill/agent run telemetry entirely locally. No external service, no account, no CDN — everything lives in .ag-skill/telemetry/runs.jsonl inside the repository you are working in.

Because ag-skill is an installer CLI and not running inside Copilot, Claude, or Cursor, it cannot silently intercept token usage from those tools. Telemetry is therefore self-reported: after the agent finishes, you call one of the observe sub-commands and pass your own estimates.


Important: what each command does​

CommandReads dataWrites data
ag-skill observe✅ displays records❌
ag-skill observe record❌✅ appends one record
ag-skill observe from-copilotreads transcript✅ appends one record (with --skill)
ag-skill observe from-claudereads session✅ appends one record (with --skill)
ag-skill observe estimate-tokens❌❌
ag-skill stats✅ aggregates records❌
ag-skill dashboard✅ reads records✅ writes .ag-skill/dashboard.html

None of these commands execute agents. Run your agent first, then record after the fact.


Storage​

ItemPath
Telemetry log.ag-skill/telemetry/runs.jsonl
HTML dashboard.ag-skill/dashboard.html (default)

Each line in runs.jsonl is one JSON object:

{"ts":"2026-07-28T14:02:11Z","skill":"ddd-aggregate-design","agent":"ag-coder","model":"gpt-5","promptTokens":3200,"completionTokens":1800,"durationMs":12400,"status":"success"}
FieldTypeNotes
tsstringUTC timestamp, ISO 8601 — auto-generated
skillstringSkill name
agentstringAgent name, empty string if omitted
modelstringModel name, empty string if omitted
promptTokensintEstimated or exact prompt tokens
completionTokensintEstimated or exact completion tokens
durationMsintWall-clock duration in milliseconds
statusstringsuccess, failure, error, or any custom string

The file is safe to edit by hand. Malformed lines are silently skipped by all read commands.


Typical workflow​

Windows (PowerShell)​

# 1. Run the agent in your normal workflow (Copilot, Cursor, Claude, custom CLI, etc.)
# ag-skill does NOT intercept the run — it is logged after the fact.

# 2a. Best for VS Code Copilot Chat — auto-read the latest transcript (tokens estimated)
ag-skill observe from-copilot --skill ddd-aggregate-design --agent ag-architect --model gpt-4o --duration-ms 12400

# 2b. Best for Claude Code — auto-read the latest session (exact token counts from usage data)
ag-skill observe from-claude --skill ddd-aggregate-design --duration-ms 18500

# 2c. Pipe the agent's output straight into record (no pasting, tokens auto-estimated)
my-agent "design DDD aggregates for order service" |
ag-skill observe record --skill ddd-aggregate-design --agent ag-architect --model gpt-5 --response-stdin --duration-ms 12400

# 2d. Or point at a file the tool already wrote
ag-skill observe record `
--skill ddd-aggregate-design `
--agent ag-architect `
--model gpt-5 `
--response-file .\out\answer.md `
--duration-ms 12400

# 3. Review / stats / dashboard
ag-skill observe
ag-skill stats
ag-skill dashboard
start .ag-skill/dashboard.html

macOS / Linux (bash/zsh)​

# 2a. VS Code Copilot Chat — reads ~/Library/Application Support/... (macOS)
# or ~/.config/... (Linux)
ag-skill observe from-copilot --skill ddd-aggregate-design --agent ag-architect --model gpt-4o --duration-ms 12400

# 2b. Claude Code — reads ~/.claude/projects/<encoded-cwd>/*.jsonl
ag-skill observe from-claude --skill ddd-aggregate-design --duration-ms 18500

# 2c. Pipe
my-agent "design DDD aggregates for order service" | \
ag-skill observe record --skill ddd-aggregate-design --response-stdin --duration-ms 12400

# 2d. File
ag-skill observe record \
--skill ddd-aggregate-design \
--response-file ./out/answer.md \
--duration-ms 12400

# 3. Review
ag-skill observe
ag-skill stats
ag-skill dashboard
open .ag-skill/dashboard.html

Recording methods compared​

MethodCommandToken accuracyEffort
VS Code Copilot Chat transcriptfrom-copilot~10% (estimated)Zero — auto-detected
Claude Code sessionfrom-claudeExact (from usage data)Zero — auto-detected
Pipe stdinobserve record --response-stdin~10% (estimated)One pipe
Response fileobserve record --response-file~10% (estimated)Point at file
Exact API countsobserve record --prompt-tokens --completion-tokensExactSupply numbers

CLI reference​

Full options and examples for each command:


Help​

ag-skill observe --help
ag-skill observe record --help
ag-skill observe estimate-tokens --help
ag-skill observe from-copilot --help
ag-skill observe from-claude --help
ag-skill stats --help
ag-skill dashboard --help