AgentTrace: How should cross-platform file-access monitoring work?

[VeloraTech]

I'm working on AgentTrace, a local-first tool for observing what AI coding agents are actually doing on a developer's machine.

The current focus is process-level visibility: identifying active agents, separating multiple instances, tracking process trees, observing commands, and optionally watching workspace changes.

The next part I want to tackle is file-access monitoring.

And this is where I have deliberately stopped implementation.

The problem

I don't just want AgentTrace to tell me:

"src/config.js changed."

I want to eventually be able to answer questions such as:

• Which process accessed this file?
• Which AI-agent session did that process belong to?
• When did the access happen?
• Was it an open/read/write/create/delete operation?
• Was the process an agent itself or a child/helper process?
• Can that event be correlated with commands and other AgentTrace observations?

This matters particularly for sensitive files.

For example, if an AI coding agent modifies an .env file, I don't want AgentTrace to simply infer:

"The agent read .env."

I want to distinguish between:

Observed:

Process X opened .env at time Y.

Observed:

Process X modified .env at time Z.

Derived:

Process X is part of Agent session A.

And leave anything about intent to interpretation rather than presenting it as fact.

Where I've hit the wall

The problem is that filesystem monitoring is not equivalent to filesystem change watching.

A normal directory/file watcher can tell me about changes, but it doesn't necessarily tell me which process caused or accessed the file.

Then the platform problem appears.

Different operating systems expose different mechanisms and different levels of access.

Linux, Windows and macOS do not give me one portable API that I can simply wrap and call this feature "cross-platform."

There are approaches involving things such as:

• Linux filesystem/event APIs
• Windows ETW / filesystem monitoring
• Windows filter drivers
• macOS Endpoint Security
• native platform-specific collectors

But these introduce different requirements, permissions, coverage, installation models, and maintenance costs.

That creates a product question rather than simply an implementation question.

What I don't want to do

I don't want to implement a Linux-specific solution, add a thin abstraction around it, and then call AgentTrace "cross-platform."

I also don't want to build a collection of weak file watchers that can only tell users when something changed while implying that AgentTrace knows which process accessed it.

And I don't want AgentTrace capturing file contents just to make the monitoring easier.

The intended direction is:

Process activity
      +
File-access events
      +
Process-tree attribution
      +
Agent identity
      ↓
Evidence

with paths and operation metadata rather than file contents by default.

The question

For people with experience in operating systems, filesystem monitoring, endpoint security, developer tooling, or cross-platform systems software:

What is the most practical architecture for building process-attributed file-access monitoring across Windows, macOS, and Linux while being honest about platform-specific limitations?

More specifically:

1. What platform-native mechanisms would you consider for each OS?
2. Which approaches can realistically work from a developer-installed CLI without requiring a kernel driver or similarly heavy installation?
3. Where are the unavoidable privilege/permission boundaries?
4. What kinds of file access cannot reliably be observed?
5. How would you correlate filesystem events back to a process tree without introducing misleading attribution?
6. Would you expose this as one common capability with different coverage levels per OS, or treat the collectors as fundamentally different capabilities?
7. Is there an existing open-source project or architecture I should study before building this myself?

I'm especially interested in practical cross-platform approaches, not necessarily a perfect solution.

I'd rather pause here, understand the ecosystem, and build something technically honest than ship a platform-specific implementation simply because I wanted to check the feature off the roadmap.

If you've worked on this problem before, I'd genuinely appreciate your perspective.

AgentTrace: a local-first flight recorder for AI coding-agent activity.

I'm building this in the open, so I'm particularly interested in hearing from people who have opinions about the architecture—even if you think my current direction is wrong.

[ECD5A]

I'd share an event format, not a claim that all three OSes provide the same coverage. Keep the current workspace-change mode useful, but make process-attributed access a separate capability.

The backend choices I'd investigate are:

• Linux: fanotify for access events with process information. Its unprivileged mode is a real limitation here: it doesn't report another process's PID. inotify doesn't identify the actor either. Also, fanotify doesn't report mmap-based file accesses/modifications. So neither is a promise of every read.
• Windows: prototype ETW FileIo plus process/thread lifecycle collection before writing a minifilter. The read/write events need joins: TTID identifies the thread, and FileKey maps through filename events. IoSize is bytes requested, not proof those bytes reached the model. Check trace-session permissions explicitly; don't silently turn a failed access collector into a change watcher.
• macOS: Endpoint Security, with deployment constraints exposed. The classic client needs entitlement/root/FDA. For supervised trace mode, macOS 27's es_new_descendants_client is worth investigating: entitlement still required, but no root/TCC; caller and descendants only, not arbitrary already-running agents. It also restricts setuid/setgid execution for non-root callers, so it isn't a transparent replacement for the classic client.

I'd normalize the operation, native source, process identity, file identity/path and outcome only as far as the event supports them. Keep an authorization request, an observed open, and a completed read distinct. Put permissions, scope, dropped-event counts and known blind spots on the collector/session record. No event should mean "not observed under this coverage", not "the file wasn't accessed".

For attribution, PID alone isn't enough. Keep PID plus start time/native generation and process-tree history at event time. Current snapshots can misattribute after PID reuse or reparenting. And an agent-root process isn't necessarily an AI conversation: multiple sessions can share a process, while a shared MCP daemon may sit outside its tree. Explicit session correlation is stronger; otherwise label the relationship as inferred or unknown.

For prior art, osquery's FIM docs show separate backends and tables per OS. I'd study that separation, not treat every file-events table as process-attributed reads. Its FIM can also hash file contents, which is a different privacy choice from your metadata-only goal.

Before expanding coverage, I'd run the same small conformance program against each backend: open without reading, ordinary read, mmap, a short-lived child, two agents sharing a directory, rename, and collector permission/loss failures. Report the actual observations per backend. Paths can be sensitive too, even with no contents captured.

That seems a practical v1: honest changes-only fallback, optional native collectors, and attribution that can say "unknown". I haven't implemented or tested those collectors; this is based on the platform APIs and your README.

[VeloraTech]

Hey my brother @ECD5A , I was have been waiting to hear your response since two days ago. I hope i am nor too forward with the way i approached or the request i made about being a collaborator

[ECD5A]

Thanks for the invitation! What kind of collaboration do you have in mind — occasional open-source contributions, or paid project work? We can discuss the details by email if that's easier.

[VeloraTech]

Well to be honest, my initial invitation was on collaborating on the open-source projects — contributing ideas, working on specific areas, and building things together. I don't currently have a defined paid role or budget that I'm offering, so I don't want to give you the wrong impression.

I'd be glad to hear your thoughts and know if you'd be interested in joining me to build these projects together.

[ECD5A]

I appreciate the invitation, but I think there's a misunderstanding here.
I already have plenty of my own projects and responsibilities, and my time is extremely limited. When I share ideas, identify architectural issues, or contribute to someone else's project, I do so voluntarily, whenever I have the time and interest. It doesn't mean I'm looking to join another team or take on additional commitments.
That's also one of the fundamental principles of open source: developers don't need formal invitations to contribute. If a project genuinely interests them, they can get involved on their own terms.
My suggestion would be to focus on developing the projects, building a clear technical direction, and letting the community grow naturally. Good projects attract contributors by demonstrating their value, not by asking people to commit.
I wish you success with NativeRelay and AgentTrace. If I find something worth contributing in the future, and have the time, I'll do so — just as I did before.
But please understand that my contributions come without obligations or expectations of ongoing involvement.

Best of luck!

[VeloraTech]

Alright bro its very much understandable and I appreciate you taking the time to share your thoughts and point out areas we could improve.

I didn't intend to create any expectations or obligations with the invitation. I saw value in your input and thought it would be great to collaborate, but I understand where you're coming from.

I'll keep focusing on developing the projects and strengthening their technical direction. You're always welcome to share your thoughts or contribute whenever something interests you and you have the time, without any expectations attached.

Thanks again, and I wish you the best with your own projects too.