trace-skill-activity

name	trace-skill-activity
description	Records and queries what agents actually did, attributed to the skill that was active, using qvr's experimental audit subsystem. Use when a user wants observability into agent or skill behavior — e.g. "track what my skills are doing", "audit agent tool calls", "which skill ran during this session", "show recent agent activity", or "export agent traces for analysis". Covers qvr audit enable, discover, status, logs, sessions, and export. Experimental and opt-in; the command surface and storage may change.
metadata	{"author":"quiver-playground","version":"2.0.0"}

Trace skill activity with qvr audit

qvr audit records what your agents actually did — every turn, tool call, and command — attributed to the skill that was active — into a local SQLite database (~/.quiver/skillops.db). Agents already keep their own session history on disk; qvr reads those native stores directly, so there is no agent configuration to touch and months of existing history back-fill on the first scan. The subsystem is experimental, opt-in, and disabled by default; its command surface, storage format, and output shapes may change.

When to use this

• The user wants visibility into agent tool/file/command activity.
• They want to attribute actions to the skill that was active.
• They want to export traces for external analysis, replay, or archival.

This is observability only — it does not change what skills are installed (that's onboard-skills) or verify their integrity (that's verify-skill-supply-chain).

How it works (two layers)

• Raw traces — the agent's own transcript lines, captured verbatim. This is the source of truth (qvr audit export, sessions show).
• Derived projection — the unified per-session model (title, model, turn/tool counts, skills) plus Turn / Tool / Skill spans projected from the raw traces, as shown by qvr audit sessions and qvr audit logs. A deriver must exist for the agent (the DERIVES column in status reports this); only deriver-backed agents are scanned.

Workflow

1. Enable capture and discover your history

enable sets ops.enabled in config and creates the database. discover scans every supported agent's native session store and records the skill-using sessions it finds; sessions that provably used no skill are counted but not stored (pass --keep-all to import everything).

qvr audit enable
qvr audit discover                      # scan every agent's session store
qvr audit discover --agent <agent>      # scan a single agent
qvr audit discover --since 90d          # bound the back-fill window
qvr audit discover --dry-run            # report what would be scanned

Scans are incremental: re-running over an unchanged store costs almost nothing, so run discover again whenever you want fresh sessions picked up. qvr ui also scans on launch and keeps rescanning while it runs, so the dashboard tracks new sessions live (--no-discover turns this off).

2. Confirm what's recorded

qvr audit status

Read the columns: DERIVES (whether qvr can project this agent's format), RECORDED (raw rows), SESSIONS (the runs they group into), and last-event time.

3. Query activity

qvr audit sessions                                  # newest-first, titled, with skills
qvr audit sessions --agent <agent> --since 24h
qvr audit sessions show <session-id>                # one session's verbatim raw lines

qvr audit logs                                      # derived spans (default 50)
qvr audit logs --kind SKILL                         # only skill spans (or LLM / TOOL)
qvr audit logs --session <session-id> --limit 0     # everything for one session

4. Export for external analysis

export streams matching raw trace rows as JSONL (one object per line) — suitable for archival, analysis, or replay:

qvr audit export > traces.jsonl
qvr audit export --session <session-id> -o session.jsonl

5. Turn it off

qvr audit disable                       # stop recording; the database stays

Gotchas

• Experimental. Treat command names, DB schema, and output shapes as unstable; pin your qvr version if you script against them.
• Skill-less sessions are not stored by default — discover counts them (the dashboard's activity panel shows the split) but keeps only skill-attributed evidence. Use --keep-all if you want everything.
• DERIVES=no ⇒ not scanned. An agent without a deriver is listed in status but its store is not ingested.
• Local only. The database lives under ~/.quiver/; nothing is sent anywhere. The qvr ui dashboard visualizes sessions and activity analytics if you prefer a browser.

Troubleshooting

• No sessions after running discover — check qvr audit status and the discover report: SEEN=0 means no store was found for that agent on this machine; SKIPPED counts sessions that used no skill (not stored by design).
• A session is missing — it likely used no skill. Re-run with qvr audit discover --keep-all to import everything.
• Want the verbatim transcript, not spans — use qvr audit sessions show <id> or qvr audit export, which read raw traces rather than the derived view.