Audit Filesystem Changes

Inspect and analyze what an agent did during a session

AgentFS records every file operation and tool call, giving you complete visibility into agent behavior. This is essential for debugging, compliance, and understanding how agents work.

Viewing the Timeline

See a chronological list of tool calls:

agentfs timeline my-session

Output:

ID   TOOL                 STATUS       DURATION STARTED
4    execute_code         pending            -- 2024-01-05 09:44:20
3    api_call             error           300ms 2024-01-05 09:44:15
2    read_file            success          50ms 2024-01-05 09:44:10
1    web_search           success        1200ms 2024-01-05 09:43:45

Filtering Results

Show only specific tool types:

agentfs timeline my-session --filter web_search

Show only errors:

agentfs timeline my-session --status error

Limit number of entries:

agentfs timeline my-session --limit 20

JSON Output

For programmatic analysis:

agentfs timeline my-session --format json

[
  {
    "id": 1,
    "name": "web_search",
    "status": "success",
    "started_at": 1704447825,
    "completed_at": 1704447826,
    "duration_ms": 1200,
    "parameters": {"query": "AI agents"},
    "result": {"results": ["result1", "result2"]}
  }
]

Inspecting Files

List all files in a session:

agentfs fs ls my-session

Output:

d artifacts
f config.json
f output.txt

List a subdirectory:

agentfs fs ls my-session /artifacts

Read file contents:

agentfs fs cat my-session /output.txt

Viewing Changes (Diff)

See what changed compared to the original filesystem:

agentfs diff my-session

This shows:

• New files created
• Modified files
• Deleted files

Querying with SQL

Since AgentFS uses SQLite, you can run arbitrary queries:

Turso

tursodb .agentfs/my-session.db

SQLite

sqlite3 .agentfs/my-session.db

Example queries:

-- Find all tool calls that took longer than 1 second
SELECT name, duration_ms
FROM toolcalls
WHERE duration_ms > 1000;

-- Count tool usage by type
SELECT name, COUNT(*) as count
FROM toolcalls
GROUP BY name
ORDER BY count DESC;

-- Find files modified in the last hour
SELECT path, mtime
FROM fs_inode
WHERE mtime > strftime('%s', 'now', '-1 hour');

-- Get total bytes written
SELECT SUM(size) as total_bytes
FROM fs_inode
WHERE mode & 0170000 = 0100000;  -- regular files only

Use Cases

Debugging Agent Failures

When an agent fails, use the timeline to understand what happened:

# See recent activity
agentfs timeline my-session --limit 20

# Focus on errors
agentfs timeline my-session --status error

# Check what files were created/modified
agentfs fs ls my-session

Performance Analysis

Find slow operations:

SELECT name, AVG(duration_ms) as avg_ms, COUNT(*) as count
FROM toolcalls
GROUP BY name
ORDER BY avg_ms DESC;

Compliance Auditing

Export a complete record of agent activity:

agentfs timeline my-session --format json > audit-log.json

Next Steps

Overlay Filesystem

Understanding copy-on-write

Syncing

Sync sessions to Turso Cloud