GitHub - cursor/agent-trace: A standard format for tracin...

Version: 0.1.0
Status: RFC
Date: January 2026

Abstract

Agent Trace is an open specification for tracing AI-generated code. It provides a vendor-neutral format for recording AI contributions alongside human authorship in version-controlled codebases.

Motivation
Goals
Non-Goals
Terminology
Architecture Overview
Core Specification
Extensibility
Reference Implementation
Appendix

1. Motivation

As agents write more code, it's important to understand what came from AI versus humans. This attribution is both the models used as well as the related agent conversations. Agent Trace defines an open, interoperable standard for recording this attribution data.

2. Goals

Interoperability: Any compliant tool can read and write attribution data.
Granularity: Support attribution for models used at file and line granularity.
Extensibility: Vendors can add custom metadata without breaking compatibility.
Human & Agent Readable: Attribution data is readable without special tooling.

3. Non-Goals

Code Ownership: Agent Trace does not track legal ownership or copyright.
Training Data Provenance: We don't track what training data influenced AI outputs.
Quality Assessment: We don't evaluate whether AI contributions are good or bad.
UI Agnostic: Agent Trace does not require any specific interface.

4. Terminology

Term	Definition
Contribution	A unit of code change (addition, modification, or deletion)
Contributor	The entity that produced a contribution (human or AI)
Trace Record	Metadata describing a contribution's origin

Contributor Types

Type	Code	Description
Human	`human`	Code authored directly by a human developer
AI	`ai`	Code generated by AI
Mixed	`mixed`	Human-edited AI output or AI-edited human code
Unknown	`unknown`	Origin cannot be determined

5. Architecture Overview

Agent Trace is a data specification, not a product. It defines how to record attribution data. Storage mechanisms are implementation-defined. The spec is unopinionated about where traces live.

6. Core Specification

6.1 Trace Record Schema

The fundamental unit of Agent Trace is the Trace Record:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://agent-trace.dev/schemas/v1/trace-record.json",
  "title": "Agent Trace Record",
  "type": "object",
  "required": ["version", "id", "timestamp", "files"],
  "properties": {
    "version": {
      "type": "string",
      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
      "description": "Agent Trace specification version (e.g., '1.0.0')"
    },
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "Unique identifier for this trace record"
    },
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "description": "RFC 3339 timestamp when trace was recorded"
    },
    "vcs": {
      "$ref": "#/$defs/vcs",
      "description": "Version control system information for this trace"
    },
    "tool": {
      "$ref": "#/$defs/tool",
      "description": "The tool that generated this trace"
    },
    "files": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/file"
      },
      "description": "Array of files with attributed ranges"
    },
    "metadata": {
      "type": "object",
      "description": "Additional metadata for implementation-specific or vendor-specific data"
    }
  },
  "$defs": {
    "vcs": {
      "type": "object",
      "required": ["type", "revision"],
      "properties": {
        "type": {
          "type": "string",
          "enum": ["git", "jj", "hg", "svn"],
          "description": "Version control system type"
        },
        "revision": {
          "type": "string",
          "description": "Revision identifier (e.g., git commit SHA, jj change ID)"
        }
      }
    },
    "tool": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "version": { "type": "string" }
      }
    },
    "file": {
      "type": "object",
      "required": ["path", "conversations"],
      "properties": {
        "path": {
          "type": "string",
          "description": "Relative file path from repository root"
        },
        "conversations": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/conversation"
          },
          "description": "Array of conversations that contributed to this file"
        }
      }
    },
    "contributor": {
      "type": "object",
      "required": ["type"],
      "properties": {
        "type": {
          "type": "string",
          "enum": ["human", "ai", "mixed", "unknown"]
        },
        "model_id": {
          "type": "string",
          "maxLength": 250,
          "description": "The model's unique identifier following models.dev convention (e.g., 'anthropic/claude-opus-4-5-20251101')"
        }
      }
    },
    "conversation": {
      "type": "object",
      "required": ["ranges"],
      "properties": {
        "url": {
          "type": "string",
          "format": "uri",
          "description": "URL to look up the conversation that produced this code"
        },
        "contributor": {
          "$ref": "#/$defs/contributor",
          "description": "The contributor for ranges in this conversation (can be overridden per-range)"
        },
        "ranges": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/range"
          },
          "description": "Array of line ranges produced by this conversation"
        },
        "related": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["type", "url"],
            "properties": {
              "type": { "type": "string" },
              "url": { "type": "string", "format": "uri" }
            }
          },
          "description": "Other related resources"
        }
      }
    },
    "range": {
      "type": "object",
      "required": ["start_line", "end_line"],
      "properties": {
        "start_line": { "type": "integer", "minimum": 1 },
        "end_line": { "type": "integer", "minimum": 1 },
        "content_hash": {
          "type": "string",
          "description": "Hash of attributed content for position-independent tracking"
        },
        "contributor": {
          "$ref": "#/$defs/contributor",
          "description": "Override contributor for this specific range (e.g., for agent handoffs)"
        }
      }
    }
  }
}

6.2 Example Trace Record

{
  "version": "0.1.0",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-01-23T14:30:00Z",
  "vcs": {
    "type": "git",
    "revision": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  },
  "tool": {
    "name": "cursor",
    "version": "2.4.0"
  },
  "files": [
    {
      "path": "src/utils/parser.ts",
      "conversations": [
        {
          "url": "https://api.cursor.com/v1/conversations/12345",
          "contributor": {
            "type": "ai",
            "model_id": "anthropic/claude-opus-4-5-20251101"
          },
          "ranges": [
            {
              "start_line": 42,
              "end_line": 67,
              "content_hash": "murmur3:9f2e8a1b"
            }
          ],
          "related": [
            {
              "type": "session",
              "url": "https://api.cursor.com/v1/sessions/67890"
            }
          ]
        }
      ]
    },
    {
      "path": "src/utils/helpers.ts",
      "conversations": [
        {
          "url": "https://api.cursor.com/v1/conversations/12345",
          "contributor": {
            "type": "ai",
            "model_id": "openai/gpt-4o"
          },
          "ranges": [
            {
              "start_line": 10,
              "end_line": 25
            }
          ]
        }
      ]
    }
  ],
  "metadata": {
    "confidence": 0.95,
    "dev.cursor": {
      "workspace_id": "ws-abc123"
    }
  }
}

6.3 Attribution Ranges

Ranges are grouped by conversation, with contributor metadata at the conversation level. This reduces cardinality when one conversation produces many ranges.

Line-level attribution:

{
  "files": [
    {
      "path": "src/utils.ts",
      "conversations": [
        {
          "url": "https://api.example.com/v1/conversations/abc",
          "contributor": {
            "type": "ai",
            "model_id": "anthropic/claude-sonnet-4-20250514"
          },
          "ranges": [
            { "start_line": 10, "end_line": 25 },
            { "start_line": 30, "end_line": 45 },
            { "start_line": 80, "end_line": 95 }
          ]
        },
        {
          "url": "https://api.example.com/v1/conversations/def",
          "contributor": { "type": "ai", "model_id": "openai/gpt-4o" },
          "ranges": [{ "start_line": 50, "end_line": 52 }]
        }
      ]
    }
  ]
}

Line numbers are 1-indexed. Ranges reference positions at the recorded revision.

6.4 Version Control Systems

Agent Trace supports multiple version control systems through the vcs field:

// Git
{ "vcs": { "type": "git", "revision": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0" } }

// Jujutsu (using change ID for stability across rebases)
{ "vcs": { "type": "jj", "revision": "kkmpptxz" } }

// Mercurial
{ "vcs": { "type": "hg", "revision": "a1b2c3d4e5f6" } }

The revision field format is VCS-specific:

git: 40-character hex commit SHA
jj: Change ID (stable across amend/rebase operations)
hg: Changeset identifier

6.5 Line Tracking

Line numbers in a trace refer to positions at the recorded revision, not current positions. To query ownership of a specific line of code:

Use VCS blame to find the revision that last touched line N
Look up the trace for that revision and file
Find the range containing line N

6.6 Content Hashes

For tracking attribution across code movement, use content hashes at the range level:

{
  "files": [
    {
      "path": "src/parser.ts",
      "conversations": [
        {
          "url": "https://api.example.com/v1/conversations/abc",
          "contributor": {
            "type": "ai",
            "model_id": "anthropic/claude-opus-4-5-20251101"
          },
          "ranges": [
            {
              "start_line": 10,
              "end_line": 25,
              "content_hash": "murmur3:9f2e8a1b"
            }
          ]
        }
      ]
    }
  ]
}

The hash applies to the specific range, allowing tracking even when code moves within or between files.

6.7 Model Identifier

Model identifiers follow the models.dev convention:

{
  "contributor": {
    "type": "ai",
    "model_id": "anthropic/claude-opus-4-5-20251101"
  }
}

Format: provider/model-name

6.8 Linked Resources

Each conversation has a url field and optional related array for linking to related sub-resources:

{
  "files": [
    {
      "path": "src/api.ts",
      "conversations": [
        {
          "url": "https://api.example.com/v1/conversations/abc123",
          "contributor": {
            "type": "ai",
            "model_id": "anthropic/claude-opus-4-5-20251101"
          },
          "ranges": [{ "start_line": 10, "end_line": 50 }],
          "related": [
            {
              "type": "session",
              "url": "https://api.example.com/v1/sessions/xyz789"
            },
            {
              "type": "prompt",
              "url": "https://api.example.com/v1/prompts/def456"
            }
          ]
        }
      ]
    }
  ]
}

7. Extensibility

7.1 Specification Versioning

Major version: breaking changes to required fields
Minor version: additive changes (new optional fields)

7.2 Metadata

The metadata field can include implementation or vendor-specific data:

{
  "metadata": {
    "confidence": 0.95,
    "post_processing_tools": ["prettier@3.0.0"],
    "dev.cursor": {
      "workspace_id": "ws-abc123"
    }
  }
}

Vendors may use reverse-domain notation (e.g., dev.cursor, com.github.copilot) within metadata to avoid key collisions.

8. Reference Implementation

A reference implementation is provided in the reference/ directory, demonstrating how to integrate Agent Trace with coding agents. The implementation includes:

trace-store.ts: A storage layer for reading and writing trace records
trace-hook.ts: Hook integration for automatic trace capture on file changes

The reference is an example for Cursor or Claude Code, but the patterns are applicable to any AI coding agent.

Appendix

A. Minimal Valid Trace Record

{
  "version": "0.1.0",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-01-25T10:00:00Z",
  "files": [
    {
      "path": "src/app.ts",
      "conversations": [
        {
          "contributor": { "type": "ai" },
          "ranges": [{ "start_line": 1, "end_line": 50 }]
        }
      ]
    }
  ]
}

B. MIME Type

Type	MIME Type
Trace Record	`application/vnd.agent-trace.record+json`

C. FAQ

How should I store the traces?

This spec intentionally does not define how traces are stored. This could be local files, git notes, a database, or anything else.

How should I handle rebases or merge commits?

We expect to see different implementations in open source. This may influence the spec in the future. We are open to feedback.

What happens when agents create scripts to write code?

This is left to the implementation. Code generated this way should still be attributed to the agent. For example, you could snapshot files before and after the script runs, then use git diff to determine what the agent added.

License

This specification is released under CC BY 4.0.

Contributing

Thanks to the following partners for helping shape Agent Trace:

This specification is accepting suggestions on GitHub.

推荐订阅源

Hacker News - Newest: "AI"