Interactive Monitoring Tool

File Access Monitor

Scan directories for recent file activity. See exactly which files were created and modified during agent sessions — with a full timeline.

Install

Get the CLI Tool

Run the file monitor locally as an MCP server, or try it online below.

npx @clinetools/file-monitor
Requires Node.js 18+
  • Real-time file activity scanning via fs.stat
  • Chronological timeline of file operations
  • Time window filtering (5m, 1h, 24h, 7d)
  • Most active directory analysis
  • Zero config — just run with npx
Tutorial

How to Use It

Three ways to monitor file activity — pick the one that fits your workflow.

1

Try Online

Use the interactive demo below to explore sample scan results — no install needed.

↓ Jump to interactive demo
2

Use via CLI

Run as a local MCP server and connect any MCP-compatible client.

npx @clinetools/file-monitor
3

Add to Cline / Claude Code

Add the tool to your MCP settings for instant access from your AI assistant.

"file-monitor": { "command": "npx", "args": ["@clinetools/file-monitor"] }

MCP Client Configuration 

{
  "mcpServers": {
    "file-monitor": {
      "command": "npx",
      "args": ["@clinetools/file-monitor"]
    }
  }
}

Example: scan_file_activity — normal session 

// Call the tool:
scan_file_activity({ directory: "/home/user/my-project", timeWindow: "1h" })

// Output:
{
  "summary": {
    "directory": "/home/user/my-project",
    "timeWindow": "last 1h",
    "totalFilesScanned": 342,
    "totalActivity": 5,
    "operationCounts": { "created": 1, "modified": 3, "accessed": 1 }
  },
  "timeline": [
    { "timestamp": "2026-02-08T14:32:10Z", "operation": "modified", "path": "src/index.ts", "size": 4210 },
    { "timestamp": "2026-02-08T14:28:45Z", "operation": "modified", "path": "src/api/router.ts", "size": 8920 },
    { "timestamp": "2026-02-08T14:15:02Z", "operation": "created", "path": "src/utils/helpers.ts", "size": 1580 },
    { "timestamp": "2026-02-08T14:10:30Z", "operation": "modified", "path": "config/database.json", "size": 620 },
    { "timestamp": "2026-02-08T13:55:18Z", "operation": "accessed", "path": "README.md", "size": 3400 }
  ]
}

Example: scan_file_activity — suspicious burst 

// Call the tool:
scan_file_activity({ directory: "/home/user", timeWindow: "1h" })

// Output:
{
  "summary": {
    "directory": "/home/user",
    "timeWindow": "last 1h",
    "totalFilesScanned": 1204,
    "totalActivity": 34,
    "operationCounts": { "created": 12, "modified": 18, "accessed": 4 }
  },
  "mostActiveDirectories": [
    { "path": "/home/user/.ssh", "activityCount": 5 },
    { "path": "/home/user/.config", "activityCount": 8 },
    { "path": "/home/user/projects/src", "activityCount": 12 }
  ],
  "timeline": [
    { "timestamp": "2026-02-08T14:31:58Z", "operation": "accessed", "path": ".ssh/id_rsa.pub", "size": 740 },
    { "timestamp": "2026-02-08T14:31:55Z", "operation": "modified", "path": ".ssh/config", "size": 1200 },
    { "timestamp": "2026-02-08T14:31:52Z", "operation": "accessed", "path": ".npmrc", "size": 340 },
    { "timestamp": "2026-02-08T14:31:48Z", "operation": "modified", "path": ".env", "size": 890 },
    { "timestamp": "2026-02-08T14:31:44Z", "operation": "modified", "path": ".env.production", "size": 1120 },
    { "timestamp": "2026-02-08T14:31:40Z", "operation": "accessed", "path": ".bash_history", "size": 24800 },
    "... 28 more entries within a 2-minute window"
  ]
}
Live Demo

Try It Online

Click a demo scenario to visualize file activity from different agent sessions.

Click a demo scenario above to visualize file activity results.

Activity Timeline

How It Works

Understanding File Activity Scanning

Learn how the monitor detects and classifies file operations during agent sessions.

Timestamp Analysis

Files carry four timestamps: birthtime, mtime, atime, and ctime. By comparing these against session windows, we identify exactly what happened to each file.

Operation Detection

Created (birthtime in window), Modified (mtime in window, different from birthtime), and Accessed (atime in window) — three distinct operations revealed by stat().

Directory Summarization

Aggregating activity by directory reveals hotspots. A sudden spike in /home/.ssh/ means something very different than activity in /src/components/.

Time Window Filtering

Relative windows (5m, 1h, 24h) or ISO timestamps let you zoom into exact session periods. Narrow windows catch bursty suspicious behavior.

Path Pattern Matching

Glob filtering (*.ts, *.env*) narrows scans to specific file types. Essential for targeted auditing of config files or source code.

Agent Session Auditing

Run scan_file_activity after every agent session to verify the agent only touched expected files. Compare the timeline against the agent's stated actions.

Want Full Session Monitoring?

Set up continuous file monitoring for your agent development environment.

Learn More