kenn-io--agentsview/docs/stats.md

title, description

title	description
Stats	Experimental workspace analytics via agentsview stats

agentsview stats is a top-level CLI command added in 0.23.0 for window-scoped reporting over your local session archive. It emits a human-readable summary by default and can also emit JSON for scripts and downstream tooling.

!!! warning "Experimental" agentsview stats is experimental. The human-readable output is not stable, and the exact JSON output may change in future releases. Treat it as a moving surface and parse it defensively.

What It Reports

The command pulls together several categories of information:

• Session totals — total sessions, human versus automation sessions, total messages, total user messages
• Session archetypes — automation, quick, standard, deep, and marathon buckets
• Session shape — mean duration, user-message counts, peak context, and tools-per-turn
• Velocity — turn-cycle timing, first-response timing, and messages per active hour
• Tool, model, and agent mix — top tool categories plus token and session mix by model and agent
• Claude-only optional sections — cache economics, plan-mode adoption, subagent activity, and skill counts when the window has compatible data
• Temporal activity — active UTC-hour buckets plus the reporter timezone
• Git outcomes — commit, LOC, file-change, and optional PR totals for repos enclosing session working directories
• Session outcomes — aggregate counts, grade distribution, retry rate, compactions per session, and edit churn. The raw four outcomes (completed, abandoned, errored, unknown) are rolled up here into three buckets: success (= completed), failure (= abandoned or errored), and unknown (= unknown plus any unrecognized value). The rollup applies to both the human summary and the JSON outcomes block.
• Code attribution — optional AI-authored code attribution from host-local attribution sources such as Cursor.

Automation Scope

As of 0.25.0, agentsview stats uses each session's stored is_automated value as the authority for human versus automation scope. That classification drives session totals, archetypes, the scope_human distributions, and the human-scoped agent_portfolio fields (by_sessions_human, by_messages_human, by_tokens_human, and primary_human). scope_all still includes every session in the selected window.

For the user_messages.scope_human distribution only, sessions with fewer than two user messages are omitted from that distribution's mean and buckets because the human bucket set starts at two user messages. They still contribute to scope_all and to the session totals according to their is_automated value.

Usage

# Human-readable summary for the last 28 days
agentsview stats

# Fixed date range as JSON
agentsview stats --format json --since 2026-04-01 --until 2026-04-15

# Narrow to one agent and one project
agentsview stats --agent claude --include-project my-app

Flags

Flag	Default	Description
--format	human	Output format: human or json
--json	false	Alias for --format json
--since	28d	Start of window, either a compact duration like 28d or a YYYY-MM-DD date
--until	now	End of window as YYYY-MM-DD
--agent	all	Restrict to one agent, or leave as all
--include-project		Repeatable project allowlist
--exclude-project		Repeatable project blocklist
--timezone	local	Timezone used for temporal reporting

Data Scope

Session-derived stats summarize the selected window in the local AgentsView archive. When the command talks to a local SQLite daemon, the daemon answers from that same archive. If it falls back to a direct read-only SQLite open, it reads the archive file directly.

Code attribution is different: it is not synced session data. When present, the Cursor source in the code_attribution.sources array is read live from the Cursor attribution database on the host answering the stats request: ~/.cursor/ai-tracking/ai-code-tracking.db by default, or the path in AGENTSVIEW_CURSOR_ATTRIBUTION_DB.

That means the Cursor source is machine-local. It is not aggregated across synced machines, is not pushed to PostgreSQL, and is not available from PostgreSQL read-only serving. Project filters cannot be represented against Cursor's attribution database, so project-filtered stats include a Cursor source with status: "unsupported_filter" instead of silently reporting zero attribution.

Human Output

The default human output is organized into named sections. Depending on the data available in the selected window, you may see:

• Totals
• Archetypes
• Session shape
• Velocity
• Tool mix
• Model mix
• Agent portfolio
• Cache economics
• Adoption
• Temporal
• Outcome stats
• Outcomes
• Code attribution

Some sections are optional. For example, git-based outcome stats are omitted when AgentsView cannot derive any repos from the sessions in the selected window, and Claude-only sections are omitted when the window has no compatible data.

JSON Output

JSON output currently carries schema_version: 1 and is divided into top-level blocks such as:

• window
• filters
• totals
• distributions
• archetypes
• velocity
• tool_mix
• model_mix
• agent_portfolio
• temporal
• generated_at

Optional blocks may also appear:

• cache_economics
• adoption
• outcome_stats
• outcomes
• code_attribution

code_attribution.sources lists attribution sources that contributed to the selected stats request. Each source carries provider, scope, status, optional warnings, and provider-specific metrics. The Cursor source currently uses scope: "machine_local".

Current source statuses are available, empty, unavailable, error, and unsupported_filter. Check a source's warnings before interpreting missing metrics or zero counters as zero AI code activity. If an agent filter excludes Cursor, the Cursor source is omitted. If no source contributes, the whole code_attribution block is omitted.

Even though the JSON currently includes a version number, it is still best to treat it as experimental and additive: expect new fields, optional blocks, and formatting changes over time.

Git And PR Aggregation

agentsview stats uses session working directories to discover git repositories and then aggregates git activity for the configured author in each repo.

That includes:

• commit counts
• lines added and removed
• files changed

Pull-request counts are optional and use CLI-oriented GitHub token sources:

• If AGENTSVIEW_GITHUB_TOKEN is set, AgentsView uses it.
• Otherwise it tries gh auth token.
• If neither source yields a token, PR counts are omitted instead of being reported as zero.

This distinction matters in JSON output: a missing PR field means "GitHub lookup not configured", not "configured and zero PRs found".

Relationship To Session Intelligence

Session Intelligence is the per-session surface for health scores, outcomes, and signal inspection.

agentsview stats is the aggregate surface: it summarizes the whole archive over a window rather than explaining one session at a time.