Overview
The integration between the file watcher and Work-Wiki transforms raw file system events into actionable transparency, enabling the Human-AI feedback loop.Copy
+==============================================================================+
| |
| FILE WATCHER INTEGRATION OVERVIEW |
| |
+==============================================================================+
| |
| THE FLOW |
| |
| +------------------+ |
| | AI Agent | |
| | (Claude Code, | |
| | Cursor, etc.) | |
| +--------+---------+ |
| | |
| | Creates/Modifies Files |
| v |
| +------------------+ |
| | FILE SYSTEM | |
| | (Projects) | |
| +--------+---------+ |
| | |
| | Platform Events |
| v |
| +------------------+ +------------------+ |
| | File Watcher |----->| SQLite Database | |
| | (Rust Daemon) | | (file_events) | |
| +--------+---------+ +--------+---------+ |
| | | |
| | Socket Push | Query |
| v v |
| +------------------+ +------------------+ |
| | Monolex App |<-----| Work-Wiki | |
| | (Tauri) | | (Analyzer) | |
| +--------+---------+ +--------+---------+ |
| | | |
| | | Attribution |
| v v |
| +--------------------------------------------------+ |
| | | |
| | TRANSPARENCY LAYER | |
| | | |
| | "AI created file X at timestamp Y" | |
| | "AI modified 47 lines in file Z" | |
| | | |
| +--------------------------------------------------+ |
| | |
| v |
| +--------------------------------------------------+ |
| | | |
| | HUMAN SEES --> HUMAN RESPONDS | |
| | | |
| +--------------------------------------------------+ |
| | |
| v |
| +------------------+ |
| | FEEDBACK LOOP | |
| | COMPLETE | |
| +------------------+ |
| |
+==============================================================================+
Complete Data Flow
From file change to transparency visualization.Copy
+==============================================================================+
| |
| COMPLETE DATA FLOW DIAGRAM |
| |
+==============================================================================+
| |
| PHASE 1: FILE SYSTEM EVENTS |
| ============================ |
| |
| AI Agent writes file |
| | |
| v |
| +------------------+ |
| | Kernel FS Layer | |
| +--------+---------+ |
| | |
| | Platform-specific event notification |
| v |
| +------------------+ |
| | Cross-platform | |
| | Watcher | (Abstraction layer) |
| +--------+---------+ |
| | |
| |
| PHASE 2: EVENT FILTERING |
| ========================= |
| | |
| v |
| +------------------+ |
| | Debouncer | (500ms debounce window) |
| | (Rust crate) | |
| | | Coalesces rapid changes |
| | | Deduplicates modify events |
| +--------+---------+ |
| | |
| v |
| +------------------+ |
| | 5-Level Filter | |
| | | |
| | 1. Extensions | |
| | 2. System Paths | |
| | 3. Build Folders | |
| | 4. Dotfiles | |
| | 5. User Rules | |
| +--------+---------+ |
| | | |
| | | IGNORE (discarded) |
| | +----> (no DB write) |
| | |
| | WATCH |
| v |
| +------------------+ |
| | Event Handler | |
| | | |
| | - Extract ts | |
| | - Get event_type | |
| | - Compute paths | |
| | - Get file_size | |
| +--------+---------+ |
| | |
| |
| PHASE 3: DATA PERSISTENCE |
| ============================ |
| | |
| +----+----+ |
| | | |
| v v |
| +--------+ +-------------+ |
| | SQLite | | Notification| |
| | write | | Manager | |
| | | | | |
| | INSERT | | Broadcast | |
| +--------+ +-------------+ |
| | | |
| v v |
| Events table Push to clients |
| (JSON over socket) |
| |
| PHASE 4: CONSUMPTION BY WORK-WIKI |
| ===================================== |
| | | |
| v v |
| +--------+ +-------------+ |
| | Query | | Real-time | |
| | by time| | subscription| |
| +--------+ +-------------+ |
| | | |
| +------+-------+ |
| | |
| v |
| +------------------+ |
| | Work-Wiki | |
| | Attribution | |
| | Analysis | |
| | | |
| | - Timeline view | |
| | - Project stats | |
| | - AI detection | |
| +--------+---------+ |
| | |
| v |
| +------------------+ |
| | TRANSPARENCY | |
| | ACHIEVED | |
| | | |
| | Human can see | |
| | what AI did | |
| +------------------+ |
| |
+==============================================================================+
Event Types and Interpretation
Each event type has specific meaning for Work-Wiki analysis.Copy
+==============================================================================+
| |
| FILE EVENT TYPES AND WORK-WIKI INTERPRETATION |
| |
+==============================================================================+
| |
| +========+==========================+================================+ |
| | TYPE | FILE SYSTEM MEANING | WORK-WIKI INTERPRETATION | |
| +========+==========================+================================+ |
| | | | | |
| | create | New file appeared | AI/Human wrote new code | |
| | | in watched directory | or documentation | |
| | | | | |
| | | | Possible scenarios: | |
| | | | - New feature implementation | |
| | | | - New test file | |
| | | | - New documentation | |
| | | | - Configuration file | |
| | | | | |
| +--------+--------------------------+--------------------------------+ |
| | | | | |
| | change | Existing file modified | AI/Human edited existing | |
| | | (content or metadata) | code or content | |
| | | | | |
| | | | Possible scenarios: | |
| | | | - Bug fix | |
| | | | - Feature enhancement | |
| | | | - Refactoring | |
| | | | - Documentation update | |
| | | | | |
| +--------+--------------------------+--------------------------------+ |
| | | | | |
| | unlink | File deleted | AI/Human removed file | |
| | | from filesystem | (cleanup, refactoring) | |
| | | | | |
| | | | Possible scenarios: | |
| | | | - Dead code removal | |
| | | | - File consolidation | |
| | | | - Cleanup temporary files | |
| | | | - Project restructure | |
| | | | | |
| +========+==========================+================================+ |
| |
| ATTRIBUTION HEURISTICS: |
| |
| +----------------------------------------------------------------+ |
| | Timestamp Analysis | |
| | ------------------- | |
| | ts within AI session window --> likely AI work | |
| | ts during human typing --> likely human work | |
| | Burst of related changes --> coordinated work (likely AI) | |
| +----------------------------------------------------------------+ |
| |
| +----------------------------------------------------------------+ |
| | Path Analysis | |
| | ------------- | |
| | .claude/ changes --> definitely AI-related | |
| | .niia/ changes --> system activity | |
| | Multiple related files --> coordinated change (likely AI) | |
| +----------------------------------------------------------------+ |
| |
+==============================================================================+
Database Schema for Work-Wiki
The database structure enables powerful querying and analysis.Copy
+==============================================================================+
| |
| DATABASE SCHEMA FOR WORK-WIKI INTEGRATION |
| |
+==============================================================================+
| |
| file_events TABLE |
| ================== |
| |
| +================+============+========================================+ |
| | Column | Type | Purpose for Work-Wiki | |
| +================+============+========================================+ |
| | id | INTEGER PK | Unique event identifier | |
| | | | Used for pagination, deduplication | |
| +----------------+------------+----------------------------------------+ |
| | ts | INTEGER | CRITICAL: When did the change happen? | |
| | | NOT NULL | | |
| | | | - Enables timeline reconstruction | |
| | | | - AI session correlation | |
| | | | - Human activity pattern detection | |
| | | | - Stored as milliseconds since epoch | |
| +----------------+------------+----------------------------------------+ |
| | event_type | TEXT | What happened? | |
| | | NOT NULL | | |
| | | | Values: "create" | "change" | "unlink" | |
| | | | - Enables filtering by action type | |
| | | | - Statistics aggregation | |
| +----------------+------------+----------------------------------------+ |
| | abs_path | TEXT | CRITICAL: Which file was changed? | |
| | | NOT NULL | | |
| | | | - Enables project-level analysis | |
| | | | - File-specific history | |
| | | | - AI folder detection | |
| +----------------+------------+----------------------------------------+ |
| | rel_path | TEXT | Path relative to watch root | |
| | | | | |
| | | | - Useful for project context | |
| | | | - Cleaner display in UI | |
| +----------------+------------+----------------------------------------+ |
| | basename | TEXT | Just the filename | |
| | | | | |
| | | | - Quick filtering by filename | |
| | | | - Extension-based analysis | |
| +----------------+------------+----------------------------------------+ |
| | file_size | INTEGER | How much data changed? | |
| | | | | |
| | | | - Large size = significant change | |
| | | | - Size patterns indicate work type | |
| | | | - NULL for unlink events | |
| +----------------+------------+----------------------------------------+ |
| | is_directory | BOOLEAN | Is this a directory operation? | |
| | | | | |
| | | | - Filter out directory events | |
| | | | - Focus on file changes | |
| +================+============+========================================+ |
| |
| INDEXES FOR WORK-WIKI QUERIES |
| ================================ |
| |
| +--------------------------------------------------------------------+ |
| | idx_file_events_ts ON file_events(ts DESC) | |
| | | |
| | Purpose: Time-based queries (most common) | |
| | Query: SELECT * FROM file_events WHERE ts > X ORDER BY ts DESC | |
| +--------------------------------------------------------------------+ |
| |
| +--------------------------------------------------------------------+ |
| | idx_file_events_path ON file_events(abs_path) | |
| | | |
| | Purpose: File history queries | |
| | Query: SELECT * FROM file_events WHERE abs_path = '/path/to/x' | |
| +--------------------------------------------------------------------+ |
| |
| +--------------------------------------------------------------------+ |
| | idx_file_events_type ON file_events(event_type) | |
| | | |
| | Purpose: Filter by action type | |
| | Query: SELECT * FROM file_events WHERE event_type = 'create' | |
| +--------------------------------------------------------------------+ |
| |
+==============================================================================+
Work-Wiki Query Patterns
Common queries for transparency analysis.Copy
+==============================================================================+
| |
| WORK-WIKI QUERY PATTERNS |
| |
+==============================================================================+
| |
| QUERY 1: Timeline Reconstruction |
| =================================== |
| |
| "What happened in the last hour?" |
| |
| SELECT event_type, abs_path, file_size, ts |
| FROM file_events |
| WHERE ts > (current_timestamp - 1 hour) |
| ORDER BY ts ASC; |
| |
| QUERY 2: Project Activity |
| ========================== |
| |
| "What files changed most in project X?" |
| |
| SELECT abs_path, COUNT(*) as change_count, |
| SUM(file_size) as total_bytes |
| FROM file_events |
| WHERE abs_path LIKE '/Users/dev/project-x/%' |
| AND ts > (current_timestamp - 1 day) |
| GROUP BY abs_path |
| ORDER BY change_count DESC |
| LIMIT 20; |
| |
| QUERY 3: File History |
| ======================= |
| |
| "Complete history of a specific file" |
| |
| SELECT event_type, file_size, ts |
| FROM file_events |
| WHERE abs_path = '/Users/dev/project/src/main.rs' |
| ORDER BY ts DESC |
| LIMIT 100; |
| |
| QUERY 4: Daily Statistics |
| =========================== |
| |
| "Activity breakdown by day" |
| |
| SELECT |
| DATE(ts) as date, |
| COUNT(*) as total, |
| SUM(CASE WHEN event_type = 'create' THEN 1 ELSE 0 END) as creates, |
| SUM(CASE WHEN event_type = 'change' THEN 1 ELSE 0 END) as changes, |
| SUM(CASE WHEN event_type = 'unlink' THEN 1 ELSE 0 END) as unlinks |
| FROM file_events |
| GROUP BY DATE(ts) |
| ORDER BY date DESC |
| LIMIT 30; |
| |
| QUERY 5: AI Folder Activity |
| ============================ |
| |
| "All changes in AI configuration folders" |
| |
| SELECT event_type, abs_path, ts |
| FROM file_events |
| WHERE abs_path LIKE '%/.claude/%' |
| OR abs_path LIKE '%/.niia/%' |
| OR abs_path LIKE '%/.agent/%' |
| ORDER BY ts DESC |
| LIMIT 50; |
| |
+==============================================================================+
AI Work Detection
Multiple mechanisms identify AI-generated changes.Copy
+==============================================================================+
| |
| AI WORK DETECTION MECHANISMS |
| |
+==============================================================================+
| |
| MECHANISM 1: AI CONFIGURATION FOLDERS (Direct Detection) |
| ======================================================== |
| |
| The watcher explicitly whitelists AI-related folders: |
| |
| +----------------------------------------------------------------+ |
| | Folder | Purpose | Detection Value | |
| +-----------------+----------------------------+-----------------+ |
| | /.claude/ | Claude Code settings | HIGH | |
| | | Context, session data | | |
| +-----------------+----------------------------+-----------------+ |
| | /.niia/ | NIIA AI configuration | HIGH | |
| | | Work tracking | | |
| +-----------------+----------------------------+-----------------+ |
| | /.agent/ | Generic AI agent config | MEDIUM | |
| +-----------------+----------------------------+-----------------+ |
| | /.gemini/ | Gemini AI config | MEDIUM | |
| +-----------------+----------------------------+-----------------+ |
| | /.monolex/ | Monolex-specific settings | HIGH | |
| +----------------------------------------------------------------+ |
| |
| When files in these folders change: |
| --> AI was likely active |
| --> Session began/ended |
| --> Configuration changed |
| |
| MECHANISM 2: TEMPORAL CORRELATION (Pattern Detection) |
| ====================================================== |
| |
| AI work typically shows distinct patterns: |
| |
| +----------------------------------------------------------------+ |
| | PATTERN: Burst of Coherent Changes | |
| | | |
| | ts=1000 create /proj/.claude/session-abc.json <-- Session | |
| | ts=1005 create /proj/src/new_feature.rs <-- Feature | |
| | ts=1010 change /proj/src/lib.rs <-- Imports | |
| | ts=1015 create /proj/tests/new_feature_test.rs <-- Tests | |
| | ts=1020 change /proj/Cargo.toml <-- Deps | |
| | ts=1025 change /proj/.claude/session-abc.json <-- Session | |
| | | |
| | Indicators: | |
| | - Short time span (25ms for 6 changes) | |
| | - Related files (same feature, same project) | |
| | - Session markers at start and end | |
| | - Tests created alongside implementation | |
| +----------------------------------------------------------------+ |
| |
| +----------------------------------------------------------------+ |
| | CONTRAST: Human Typing Pattern | |
| | | |
| | ts=1000 change /proj/src/main.rs | |
| | ts=15000 change /proj/src/main.rs (15 sec later) | |
| | ts=45000 change /proj/src/main.rs (30 sec later) | |
| | ts=120000 change /proj/src/main.rs (75 sec later) | |
| | | |
| | Indicators: | |
| | - Long gaps between changes (seconds to minutes) | |
| | - Same file repeatedly (editing in place) | |
| | - No session markers | |
| | - Irregular timing | |
| +----------------------------------------------------------------+ |
| |
+==============================================================================+
Real-Time Push Notification Flow
Step-by-step subscription and notification delivery.Copy
+==============================================================================+
| |
| PUSH NOTIFICATION FLOW |
| |
+==============================================================================+
| |
| STEP 1: CLIENT SUBSCRIBES |
| ========================== |
| |
| Monolex App (TypeScript) File Watcher (Rust) |
| ======================== ==================== |
| |
| const socket = connect( |
| "~/.monolex/runtime/sockets/niia/watcher-control.sock" |
| ); |
| |
| socket.write('{"type":"subscribe"}\n'); |
| | |
| +-------------------------> |
| | |
| v |
| +------------------+ |
| | ControlServer | |
| | handle_client() | |
| +--------+---------+ |
| | |
| v |
| +------------------+ |
| | Parse JSON | |
| | Subscribe cmd | |
| +--------+---------+ |
| | |
| v |
| +------------------+ |
| | Send response | |
| | {"success":true} | |
| +--------+---------+ |
| | |
| v |
| +------------------+ |
| | Register stream | |
| | in Notification | |
| | Manager | |
| +------------------+ |
| |
| <----------------------------------------------+ |
| {"success":true,"message":"Subscribed to notifications"} |
| |
| (Socket stays OPEN - now owned by NotificationManager) |
| |
| |
| STEP 2: FILE CHANGE OCCURS |
| =========================== |
| |
| AI modifies file |
| | |
| v |
| +------------------+ |
| | Kernel notifies | |
| | File system | |
| +--------+---------+ |
| | |
| v |
| +------------------+ |
| | Watcher crate | |
| | debouncer | |
| +--------+---------+ |
| | |
| v |
| +------------------+ |
| | handle_event() | |
| +--------+---------+ |
| | |
| +--------+--------+ |
| | | |
| v v |
| +--------+ +-----------------+ |
| | SQLite | | file_events | |
| | INSERT | | .push(event) | |
| +--------+ +--------+--------+ |
| | |
| v |
| +------------------+ |
| | NotificationMgr | |
| | .notify(events) | |
| +--------+---------+ |
| | |
| v |
| +------------------+ |
| | For each client: | |
| | stream | |
| | .write_all() | |
| | .flush() | |
| +------------------+ |
| |
| |
| STEP 3: CLIENT RECEIVES |
| ======================== |
| |
| Monolex App receives on socket: |
| |
| +----------------------------------------------------------------+ |
| | { | |
| | "type": "file-events-added", | |
| | "count": 1, | |
| | "events": [ | |
| | { | |
| | "ts": 1705500000000, | |
| | "event_type": "change", | |
| | "abs_path": "/Users/dev/project/src/main.rs", | |
| | "rel_path": "src/main.rs", | |
| | "size": 2048 | |
| | } | |
| | ] | |
| | } | |
| +----------------------------------------------------------------+ |
| |
| App can now: |
| --> Update Work-Wiki view in real-time |
| --> Show notification toast to human |
| --> Log activity to local metrics |
| --> Trigger UI refresh |
| |
+==============================================================================+
Performance Characteristics
Resource efficiency enables continuous monitoring.Copy
+==============================================================================+
| |
| PERFORMANCE CHARACTERISTICS |
| |
+==============================================================================+
| |
| +====================================================================+ |
| | METRIC | RUST VALUE | vs NODE.JS | |
| +====================================================================+ |
| | Binary Size | 2.6 MB | 50+ MB (with modules) | |
| | Memory Usage | ~2 MB | ~10 MB (91% reduction) | |
| | CPU (idle) | ~0.1% | ~2% (95% reduction) | |
| | Event Latency | <50ms | <100ms | |
| | Debounce Window | 500ms | 500ms (same) | |
| | DB Write Time | <1ms | ~1ms (similar) | |
| | Socket Push Time | <5ms | ~5ms (similar) | |
| +====================================================================+ |
| |
| SCALABILITY: |
| ============ |
| |
| +-- Handles 1000+ file events/second without issue |
| +-- Multiple watchers (one per watch_path) run concurrently |
| +-- Multiple socket clients supported simultaneously |
| +-- SQLite WAL mode prevents write contention |
| +-- Tokio async runtime for efficient I/O |
| |
| RELIABILITY: |
| ============ |
| |
| +-- Daemon survives main app crash (separate process) |
| +-- Lock files prevent multiple instances |
| +-- Stale lock detection and automatic cleanup |
| +-- Disconnected clients automatically removed |
| +-- Graceful shutdown via control socket |
| |
| RESOURCE COMPARISON: |
| |
| +------------------------------------------------------------------+ |
| | Memory Usage | |
| | | |
| | Node.js: ============================================ 10 MB | |
| | Rust: ==== 2 MB | |
| | | |
| | CPU Usage (idle) | |
| | | |
| | Node.js: ==================== 2% | |
| | Rust: = 0.1% | |
| | | |
| | Binary Size | |
| | | |
| | Node.js: ========================================== 50 MB | |
| | Rust: === 2.6 MB | |
| +------------------------------------------------------------------+ |
| |
+==============================================================================+
THE CENTER: Complete Feedback Loop
The integration enables all three elements of the Human-AI feedback loop.Copy
+==============================================================================+
| |
| INTEGRATION'S CONTRIBUTION TO THE CENTER |
| |
+==============================================================================+
| |
| THE CENTER: "Building an environment where Human <> AI |
| feedback loop can operate" |
| |
| The integration enables all three elements: |
| |
| +================================================================+ |
| | | |
| | 1. TRANSPARENCY | |
| | +-- File events capture EVERY change | |
| | +-- AI work folders are whitelisted | |
| | +-- Real-time push notifications | |
| | +-- SQLite provides queryable history | |
| | | |
| | 2. VISUALIZATION | |
| | +-- Work-Wiki queries file_events table | |
| | +-- Timeline reconstruction is possible | |
| | +-- Project activity views can be built | |
| | +-- AI session patterns can be visualized | |
| | | |
| | 3. FEEDBACK | |
| | +-- Human sees AI activity in real-time | |
| | +-- Human can respond via prompt | |
| | +-- Corrections are immediately captured | |
| | +-- Loop continues | |
| | | |
| +================================================================+ |
| |
| THE COMPLETE LOOP: |
| |
| +----------------------------------------------------------------+ |
| | | |
| | AI Work | |
| | | | |
| | v | |
| | +----------------+ | |
| | | File Watcher | captures file events | |
| | +-------+--------+ | |
| | | | |
| | v | |
| | +----------------+ | |
| | | Work-Wiki | presents to human | |
| | +-------+--------+ | |
| | | | |
| | v | |
| | +----------------+ | |
| | | Human sees | and understands | |
| | +-------+--------+ | |
| | | | |
| | v | |
| | +----------------+ | |
| | | Human responds | via prompt | |
| | +-------+--------+ | |
| | | | |
| | v | |
| | +----------------+ | |
| | | AI receives | feedback | |
| | +-------+--------+ | |
| | | | |
| | v | |
| | +----------------+ | |
| | | AI Work | (modified by feedback) | |
| | +-------+--------+ | |
| | | | |
| | +----> LOOP CONTINUES | |
| | | |
| +----------------------------------------------------------------+ |
| |
| This is the unity: Human <> AI as ONE motion. |
| |
| WITHOUT this integration: |
| +-- No file event capture |
| +-- No transparency data |
| +-- No visualization possible |
| +-- Feedback loop is blind |
| +-- Unity impossible |
| |
| WITH this integration: |
| +-- Every change captured |
| +-- Data available for visualization |
| +-- Human can see and respond |
| +-- Feedback loop operates |
| +-- Unity achieved |
| |
+==============================================================================+
Integration Summary
The file watcher integration provides the technical foundation for the Human-AI feedback loop through:
- Data Pipeline: File system events flow through SQLite to Work-Wiki
- Real-Time Updates: Push notifications enable immediate visibility
- AI-Aware Filtering: Whitelisting ensures meaningful tracking
- Queryable History: Database enables timeline reconstruction
- Attribution Detection: Temporal and path analysis identifies AI work