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
| Command | Reads data | Writes data |
|---|---|---|
ag-skill observe | ✅ displays records | ❌ |
ag-skill observe record | ❌ | ✅ appends one record |
ag-skill observe from-copilot | reads transcript | ✅ appends one record (with --skill) |
ag-skill observe from-claude | reads 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
| Item | Path |
|---|---|
| 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"}
| Field | Type | Notes |
|---|---|---|
ts | string | UTC timestamp, ISO 8601 — auto-generated |
skill | string | Skill name |
agent | string | Agent name, empty string if omitted |
model | string | Model name, empty string if omitted |
promptTokens | int | Estimated or exact prompt tokens |
completionTokens | int | Estimated or exact completion tokens |
durationMs | int | Wall-clock duration in milliseconds |
status | string | success, 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
| Method | Command | Token accuracy | Effort |
|---|---|---|---|
| VS Code Copilot Chat transcript | from-copilot | ~10% (estimated) | Zero — auto-detected |
| Claude Code session | from-claude | Exact (from usage data) | Zero — auto-detected |
| Pipe stdin | observe record --response-stdin | ~10% (estimated) | One pipe |
| Response file | observe record --response-file | ~10% (estimated) | Point at file |
| Exact API counts | observe record --prompt-tokens --completion-tokens | Exact | Supply numbers |
CLI reference
Full options and examples for each command:
ag-skill observe— display, record, estimate-tokens, from-copilot, from-claudeag-skill stats— aggregated statistics tablesag-skill dashboard— generate HTML dashboard
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