Agent Trace: A Standard Format for Recording Which Lines of Code Your AI Actually Wrote

Hook

When AI writes 40% of your codebase, how do you prove which lines came from GPT-4 versus your junior developer? More importantly, which tool can even tell you?

Context

The explosion of AI coding assistants—GitHub Copilot, Cursor, Cody, Tabnine, and dozens more—has created a silent attribution crisis. These tools generate millions of lines of code daily, but there's no standard way to record what the AI wrote versus what humans wrote. Each vendor uses proprietary formats, if they track attribution at all. This matters for several reasons: enterprises need to understand AI's impact on productivity and code quality, open-source projects want transparency about machine contributions, and regulatory frameworks are beginning to require disclosure of AI-generated content.

Agent Trace emerged from Cursor as an RFC-status specification to solve this interoperability problem. Rather than building yet another proprietary format, the project defines a vendor-neutral JSON schema that any AI coding tool can read and write. It's not an implementation or a product—it's a data standard, similar to how OpenAPI standardized API documentation or how SPDX standardized software bill-of-materials. The goal is ambitious: create a universal format that survives across tools, repositories, and even version control systems, allowing you to track AI contributions with the same fidelity you track human commits.

Technical Insight

Agent Trace's core abstraction is the Trace Record, a JSON structure that maps files to conversations, where each conversation contains line ranges attributed to specific contributors. The schema distinguishes between four attribution types: 'ai' (purely machine-generated), 'human' (purely human-written), 'mixed' (collaborative editing), and 'unknown' (attribution unclear). Here's what a minimal trace record looks like:

{
  "version": "0.1.0",
  "metadata": {
    "tool": "cursor",
    "toolVersion": "0.42.0",
    "timestamp": "2024-01-15T10:30:00Z"
  },
  "files": {
    "src/auth.ts": {
      "conversations": [
        {
          "id": "conv-abc123",
          "url": "https://cursor.com/conversations/abc123",
          "timestamp": "2024-01-15T10:25:00Z",
          "model": "gpt-4-turbo",
          "ranges": [
            {
              "start": 15,
              "end": 42,
              "attribution": "ai",
              "contentHash": "sha256:a3f9c8..."
            }
          ]
        }
      ]
    }
  }
}

The architecture makes several clever decisions. First, it stores attribution at line-range granularity rather than full-file level, acknowledging that real development is rarely all-AI or all-human. A developer might accept AI-generated boilerplate but hand-write the critical business logic. Second, it includes conversation context—not just 'AI wrote this,' but 'AI wrote this in response to conversation abc123 using GPT-4-turbo.' This links attribution back to the full prompt history, essential for auditing and understanding why the AI generated specific code.

The contentHash field solves a subtle but critical problem: line numbers change constantly as code evolves. If you attribute lines 15-42 to AI but then someone adds an import at line 1, should the attribution shift to 16-43? Agent Trace handles this by optionally hashing the actual content of attributed ranges. Tools can use these hashes to track attributed code even after refactoring moves it around the file. This makes attribution resilient to the natural evolution of codebases.

The spec is storage-agnostic by design. You could embed trace records in Git commit messages, store them in a .agent-trace directory alongside your code, persist them to a PostgreSQL database, or send them to a third-party attribution service. The spec doesn't care—it only defines the JSON schema. This flexibility is intentional: a startup might store traces in Git for simplicity, while an enterprise might want centralized storage with access controls and retention policies.

The extensibility model uses a metadata object that allows vendors to add custom fields without breaking compatibility. If Cursor wants to track cursor-specific telemetry like acceptance rates or edit distance, they can add it under a namespaced key. Compliant parsers ignore unknown fields, ensuring forward compatibility as the spec evolves. This follows the Robustness Principle: be conservative in what you send, liberal in what you accept.

One particularly thoughtful design choice: the spec explicitly excludes legal ownership and copyright information. Agent Trace records attribution (who created it) but makes no claims about ownership (who owns the rights). This is wise—copyright law around AI-generated content is unsettled and varies by jurisdiction. The spec stays in its lane, providing the factual record that legal and compliance teams can then interpret according to their needs.

Gotcha

Agent Trace is currently vapor-spec—it exists on paper but has no ecosystem. As of version 0.1.0, there are no publicly announced integrations, no parsing libraries in major languages, and no evidence of production adoption beyond Cursor's internal use. You can't install an npm package and start generating compliant traces today. This means early adopters face the classic chicken-and-egg problem: the spec is only valuable if multiple tools implement it, but tools won't implement it until they see adoption.

The spec also explicitly punts on several critical questions. How do you handle merge conflicts when two AI tools write different trace records for the same file? What's the lifecycle of a trace record—does it stay forever, get garbage collected, or follow retention policies? How do you aggregate traces across a repository to answer questions like 'what percentage of our codebase is AI-generated?' The spec provides the data format but no guidance on these operational concerns. Teams adopting Agent Trace will need to build their own tooling for trace lifecycle management, conflict resolution, and analytics. Finally, the line-range attribution model breaks down for highly collaborative AI interactions. If you generate code with AI, then refactor it, then ask AI to optimize your refactoring, is that 'ai', 'human', or 'mixed'? The spec offers three attribution types but real development workflows are messier than these categories suggest.

Verdict

Use Agent Trace if you're building AI coding tools and care about long-term interoperability, or if you're an enterprise that needs to track AI contributions for compliance, audit, or productivity measurement and you're willing to build supporting infrastructure. The spec is well-designed and addresses real problems, but you're betting on future adoption rather than leveraging existing tooling. Skip it if you need production-ready attribution tracking today (the ecosystem doesn't exist yet), if you're working on small projects where the overhead of maintaining line-level attribution outweighs the benefits, or if you need legal ownership tracking beyond factual attribution (the spec explicitly doesn't handle copyright). For most developers, Agent Trace is interesting but premature—watch the space and revisit when major AI coding tools announce support.