When you open a file in your project and wonder which script generated it, which AI agent wrote it, or which command produced its contents, you are facing the file lineage problem. File lineage is the practice of tracing a file back to its origin — the exact script, notebook, data source, shell command, or AI agent that created or modified it. Without this trace, teams lose visibility into how their code and data evolved, creating compliance risks, debugging nightmares, and audit failures. Emerging open-source tools like trace-file-lineage, the Agent Trace specification, and academic frameworks like PROV-AGENT now make it possible to answer this question with evidence and honest uncertainty.
The Invisible Code Problem — Why 81% of Enterprises Can’t Trace Their AI Outputs
The scale of the file lineage problem is staggering. According to the 2026 State of Product Security report, 81% of enterprises cannot track which AI agent produced their code, and only 19% have complete visibility into AI-generated contributions. Even more striking, 100% of surveyed organizations already have AI-generated code running in production. This means the vast majority of companies are operating blind — they have AI-written code in their critical systems but no way to trace which agent, model, or conversation produced it.
This “invisible code” crisis creates several concrete risks:
| Risk | Impact |
|---|---|
| Compliance violations | EU AI Act and SEC regulations require attribution of AI-generated content |
| Audit failures | No way to prove which AI agent wrote which lines during an audit |
| Debugging dead ends | Cannot trace a bug back to the agent or prompt that introduced it |
| Security blind spots | Malicious or compromised agents can inject code with no audit trail |
| Reproducibility loss | Cannot recreate the conditions that produced a given output |
The 81 percentage point gap between AI code adoption and provenance tracking represents one of the most significant compliance and operational risks in modern software development.
What Is File Lineage? — Actor, Timestamp, Action, Hash, and Parent References
File lineage, at its core, records five essential pieces of information for every file modification:
- Actor — Who or what created the file? This could be a human developer, a specific AI agent (Claude Code, Codex CLI, ChatGPT), a shell script, or a data pipeline.
- Timestamp — When was the file created or last modified? Precise UTC timestamps enable chronological reconstruction.
- Action — What type of operation occurred? Create, modify, delete, rename, or copy.
- File Hash — A cryptographic hash (SHA-256 or similar) of the file contents at the time of the action. This provides tamper evidence — if the hash changes, the file was modified after recording.
- Parent References — What input files, data sources, or previous versions produced this file? This creates the lineage chain.
The commercial guide from Fast.io formalizes this schema, adding that downstream agents and human reviewers should be able to trace outputs back through their inputs. When every file carries this metadata, you can reconstruct the full provenance chain from original data source to final output.
The VCS Gap — Why git blame Shows the Wrong Author
Traditional version control systems like Git and jujutsu (jj) were designed for human collaboration. When an AI agent writes code, git blame shows the human who committed the code — not the AI agent, model, or conversation that actually produced it. As highlighted in a detailed implementation guide on Classmethod DevIO, “git blame shows human operator, not AI model or conversation.”
This gap is fundamental. Current VCS tools have no mechanism to distinguish AI-written lines from human-written lines. When a developer uses Claude Code to generate a function, commits it, and pushes, git blame attributes those lines to the developer. The AI agent’s identity, the model version, the prompt context, and the conversation history are all lost.
The problem compounds in multi-agent workflows. If Agent A generates code, Agent B reviews and modifies it, and Agent C tests and commits it, git blame shows only Agent C’s human operator. The provenance of each line — which agent wrote it, which model generated it, which conversation produced it — is invisible.
Agent Trace — The Emerging Open Standard for AI Code Attribution
The Agent Trace specification (RFC v0.1.0), published by Cursor in January 2026, directly addresses the VCS gap. It is a vendor-neutral, open format for recording AI contributions in version control. The specification defines a JSONL sidecar file stored at .agent-trace/traces.jsonl within a repository, using a TraceRecord schema that captures:
- Which AI agent or model wrote each line
- Which conversation or session produced the code
- The exact prompt and response that generated it
- Timestamps and file paths for every modification
Agent Trace has already gained significant industry backing. Partners include Cognition (Devin) and Google Jules, and the specification was featured on ThoughtWorks Technology Radar as an “Assess” entry — indicating it is worth exploring and piloting in real projects.
The key innovation of Agent Trace is that it works alongside existing VCS workflows rather than replacing them. The .agent-trace/traces.jsonl file is committed alongside the code, creating a parallel attribution layer that git blame cannot provide. When you run git blame on a file, you see the human committer. When you check the Agent Trace file, you see the AI agent, model, and conversation that actually produced each line.
trace-file-lineage — Local-First Provenance with Honest Uncertainty
Released in July 2026, the trace-file-lineage open-source Python tool (172 GitHub stars and rapidly growing) takes a different approach. Rather than integrating with VCS, it works locally to answer a single question: which script, notebook, data, command, or AI agent produced this file?
The tool’s design philosophy emphasizes two principles:
- Evidence — It searches your local environment for clues: shell history, running processes, file metadata, notebook kernels, and AI agent logs.
- Honest uncertainty — When it cannot determine the origin with confidence, it says so. It does not fabricate answers or guess.
This local-first approach has several advantages. It requires no cloud dependency, works entirely offline, respects privacy by keeping all analysis local, and can trace files produced by any tool — not just those that explicitly support provenance recording. It is designed specifically for AI coding assistants like Claude Code, Codex CLI, and ChatGPT, but works with any file on your system.
The honest uncertainty feature is particularly important. In a world where AI agents operate across multiple tools and environments, perfect provenance is often impossible. trace-file-lineage acknowledges this limitation rather than hiding it, giving users a realistic assessment of what can and cannot be determined.
PROV-AGENT — Academic Provenance Model for Agentic Workflows
On the academic front, the PROV-AGENT framework (arXiv 2508.02866, published at IEEE International Conference on e-Science 2025) extends the W3C PROV standard — the World Wide Web Consortium’s provenance model — specifically for AI agent workflows.
PROV-AGENT introduces several innovations:
- MCP Integration — It leverages the Model Context Protocol to capture provenance data from AI agents in near real-time, without requiring agents to explicitly log their actions.
- Data Observability — It connects provenance tracking with data observability practices, enabling teams to monitor data lineage as part of their operational infrastructure.
- Cross-Facility Evaluation — The framework was tested across edge, cloud, and HPC (high-performance computing) environments, demonstrating that provenance tracking works at scale in diverse computing contexts.
As the first academic provenance model specifically designed for AI agent workflows, PROV-AGENT bridges the gap between established W3C standards and the new reality of agentic software development. It provides a theoretical foundation that practical tools like trace-file-lineage and Agent Trace can build upon.
Agent Provenance Chain and AI-Execution-Lineage — Immutable Audit Trails
The Agent Provenance Chain (agent-provenance-chain on GitHub) takes a blockchain-inspired approach to file lineage. It creates an immutable, file-based record of data lineage specifically for AI agent outputs. Each modification is recorded as a link in a chain, with cryptographic hashes ensuring that past records cannot be altered without detection.
This approach is designed for:
- Auditing — External auditors can verify the complete history of a file’s creation and modification
- Verification — Downstream consumers can verify that a file’s provenance chain is intact and unbroken
- Multi-agent workflows — When multiple agents interact with the same file, the chain records each agent’s contribution in sequence
The immutable chain approach is particularly valuable for regulated industries where audit trails are legally required. Financial services, healthcare, and government agencies that deploy AI agents need tamper-evident records of agent behavior, and Agent Provenance Chain provides exactly that.
Practical Implementation — Claude Code Hooks + jujutsu Integration
For teams that want to implement file lineage today, the most practical approach combines Claude Code hooks with the jujutsu (jj) version control system. A detailed guide on Classmethod DevIO demonstrates this exact workflow:
- Write traces via Claude Code hooks — Claude Code supports custom hooks that fire after each agent action. These hooks can write trace records to the
.agent-trace/traces.jsonlfile, capturing the agent’s identity, the model used, the conversation context, and the files modified. - Read traces with a TUI tool — A terminal user interface (TUI) tool reads the trace file and displays the provenance of any file in the repository, showing which AI agent wrote which lines.
- Commit traces alongside code — The trace file is committed to the repository, creating a permanent record that survives branch switches, rebases, and merges.
This approach works today with existing tools. No new infrastructure, no cloud services, no proprietary platforms. Any team using Claude Code and jujutsu (or Git) can implement file lineage in an afternoon.
Compliance and Regulatory Drivers — EU AI Act, SEC, and Supply Chain Security
File lineage is not just a technical convenience — it is becoming a legal requirement. Several regulatory frameworks are driving provenance adoption:
EU AI Act — The European Union’s AI Act requires transparency and documentation for AI-generated content. Organizations deploying AI agents must be able to demonstrate which AI systems produced which outputs, and file lineage provides the evidence needed for compliance.
SEC Regulations — The U.S. Securities and Exchange Commission has signaled increased scrutiny of AI use in financial services. When AI agents generate code that processes financial data or makes trading decisions, regulators expect clear attribution and audit trails.
Software Supply Chain Security — Executive orders and industry standards (EO 14028, NIST SSDF) require organizations to maintain provenance records for all software components. AI-generated code is software, and it must meet the same supply chain security standards as human-written code.
The compliance angle transforms file lineage from a “nice to have” debugging tool into a “must have” regulatory requirement. Organizations that cannot trace their AI outputs face legal exposure, audit failures, and potential fines.
Choosing the Right Approach — Local vs Cloud, Open vs Proprietary
| Approach | Best For | Tradeoffs |
|---|---|---|
| trace-file-lineage (local) | Individual developers, privacy-sensitive environments | No VCS integration, honest uncertainty may be frustrating |
| Agent Trace (VCS-integrated) | Teams using Git/jj, multi-agent workflows | Requires agent support, adds sidecar files to repos |
| PROV-AGENT (academic) | Research environments, HPC, cross-facility deployments | More complex setup, requires MCP infrastructure |
| Agent Provenance Chain (immutable) | Regulated industries, compliance-heavy environments | Overhead of chain management, less mature ecosystem |
| Commercial solutions (Fast.io, etc.) | Enterprise teams, managed compliance | Vendor lock-in, cloud dependency, ongoing cost |
The right choice depends on your team’s specific needs. For most development teams, a combination of Agent Trace for VCS attribution and trace-file-lineage for local investigation provides the best coverage.
The Future of File Lineage — C2PA Watermarking, MCP Integration, and Cross-Tool Standards
File lineage is evolving rapidly. Several trends will shape its future:
C2PA Watermarking — The Coalition for Content Provenance and Authenticity (C2PA) is developing standards for cryptographic watermarking of AI-generated content. Applied to code, C2PA could embed provenance information directly in file metadata, making it portable across tools and platforms.
MCP Integration — The Model Context Protocol, already leveraged by PROV-AGENT, is becoming a standard interface for AI agents. As more agents support MCP, provenance capture will become automatic rather than requiring explicit instrumentation.
Cross-Tool Standards — The proliferation of provenance tools (Agent Trace, trace-file-lineage, PROV-AGENT, C2PA) creates an interoperability challenge. Industry-wide standards that allow these tools to share provenance data will be essential for the ecosystem to scale.
AI-Native VCS — Some researchers are exploring version control systems designed from the ground up for AI collaboration, where provenance is a first-class concept rather than an afterthought. These systems would make file lineage automatic and universal.
FAQ
What is file lineage in the context of AI agents?
File lineage is the practice of tracing a file back to its origin — identifying which script, notebook, data source, shell command, or AI agent created or modified it. For AI agents, this means recording which agent, model version, conversation, and prompt produced each file, enabling full audit trails and reproducibility.
How does Agent Trace work with Git?
Agent Trace stores provenance data in a .agent-trace/traces.jsonl sidecar file that lives alongside your code in the repository. When an AI agent modifies a file, it writes a TraceRecord to this JSONL file. The sidecar file is committed with the code, creating a permanent attribution layer that survives all VCS operations.
Can I trace file lineage without cloud services?
Yes. The trace-file-lineage open-source tool works entirely locally with no cloud dependency. It searches your shell history, running processes, file metadata, notebook kernels, and AI agent logs to determine a file’s origin. It operates offline and respects your privacy by keeping all analysis on your machine.
Why is file lineage important for compliance?
Regulations like the EU AI Act and SEC rules require organizations to document AI-generated content and demonstrate which AI systems produced which outputs. Without file lineage, organizations cannot prove the origin of their AI-generated code, creating legal exposure, audit failures, and potential fines.
What is the difference between Agent Trace and PROV-AGENT?
Agent Trace is a practical, VCS-integrated specification for recording AI code contributions in repositories, backed by Cursor, Cognition (Devin), and Google Jules. PROV-AGENT is an academic framework that extends the W3C PROV standard for agentic workflows, integrating with the Model Context Protocol (MCP) for near real-time provenance capture across edge, cloud, and HPC environments.