Understanding Agent Traces in Span (Legacy)

Last updated: October 28, 2026

This page covers Span coding-hooks (deprecated), the earlier agent trace collector that the Span agent, auspex, replaces. For new installs and the current feature guide, see Understanding Agent Traces in Span (auspex).

Why it matters

A pull request used to be the unit of engineering work. Today much of the consequential work happens upstream, inside the agent session: scoping the task, gathering context, steering the agent. The agent trace makes that work visible. It captures the full interaction between an engineer and their AI tools, including prompts sent, MCP calls made, files edited, skills used, and tokens spent.

Span pulls traces into one system of record and, when relevant, connects each session to the PR it produced, so leaders can correlate AI-generated work with outcomes such as PR cycle time and code quality.

How it works

AI attribution. Because Span analyzes the trace alongside the diff, it can identify which specific lines in each PR an agent generated. Span matches the edits from the PR author's sessions against the PR's diff, using the chronology of file changes. You can see the results on the PR catalog page. The PR author can view a line-by-line diff showing attribution by file and by line.

Traces. The Traces page is a searchable, filterable record of AI-assisted work across your organization. Secrets are redacted before storage. Prompts and full trace conversations are visible only to the engineer who authored the trace. Click a trace to see its metadata and evaluation scores. Only the author sees the reasoning behind each score. The author can click View trace to see the full conversation with citations.

Effectiveness scorecard. Span runs agent evaluations against your traces and rolls the scores into trends you can slice by team, repo, or topic area. You can see scores over time for the overall score or each theme, filter by team or timeframe, and view the breakdown by team or by individual. Click the Traces icon on the right to see the traces that contribute most to lowering the score.

Task classification. Span classifies each trace by the kind of work performed, using 14 categories plus Unclassified. See Understanding Agent Traces in Span (auspex) for the list.

Model usage and autonomy ratio. You can also see a breakdown of model usage and the autonomy ratio: the number of agent tool calls per human prompt, averaged across sessions.

Harness health (formerly Environment Readiness) runs once a week on your busiest repositories and lists the changes to each repository's context files, rules, commands, tools, and access that would stop people from having to step in for the agent. Each recommendation is ranked by how often people stepped in and comes with evidence from the sessions and a fix prompt.

Setup

For new installs, use auspex: follow Understanding Agent Traces in Span (auspex). If your organization still runs coding-hooks, these are the steps:

  1. Approve the coding-hooks security doc.

  2. Install the hooks package (latest: coding-hooks-1.15.4) on macOS or Windows, through your MDM or by self-install. Your Span account team can share the setup steps.

  3. Reach out to your Span representative so we can enable traces for your organization. Start with a few machines, or a pilot for larger organizations.

Who can see traces, their contents, and trace reporting is controlled by four Agent Trace permissions. See Agent Trace permissions.

Things to know

  • This page is legacy. auspex replaces coding-hooks and adds a signed Windows MSI, Linux and container installs (beta), and capture for more AI tools.

  • Moving to auspex on Windows? See Retiring Span coding-hooks on Windows.

Related articles

Need help?

Contact your Span account team or reach out to support@span.app.