🔍 DiskTracker

Created by Pratham Parikh

DiskTracker is a high-performance, real-time Windows file-system observation daemon and an AI-driven CLI interface.

Decoupled through a log-structured state machine model, it reads NTFS USN (Update Sequence Number) change logs to track volume modifications instantly without locking your drive or overloading system resources. Equipped with an LLM-driven LangGraph orchestration agent, you can query your disk status, find large files, track file mutation history, and manage space interactively using natural language.

💡 Why DiskTracker?

Traditional disk space analyzers crawl the file system from scratch every time they run. This is slow, resource-heavy, and doesn't tell you when or how your space is growing.

DiskTracker resolves this by:

• Instant Tracking: Hooks into the NTFS USN Journal to catch every file creation, deletion, renaming, or modification in microseconds.
• Append-Only Performance: Real-time events are appended to a fast SQLite WAL-mode log (mutation_log) and processed by a background drain engine, preventing database locks and I/O bottlenecks.
• Conversational Control: Integrates an AI agent (disktracker ask) utilizing LangGraph to execute reads, diagnostics, and pruning actions safely under human approval.

🏗️ System Architecture

DiskTracker uses a log-structured state machine model to separate fast write paths from relational analysis:

graph TB
    subgraph Windows Kernel
        USN["NTFS USN Journal"]
    end

    subgraph "Background Daemon (disktracker daemon)"
        Watcher["USN Watcher Thread"] -->|Append-Only| MutLog[("SQLite mutation_log")]
        Scanner["Baseline Scanner"] -->|Bulk Inserts Fact-Tree| Facts[("SQLite facts DB")]
        
        Drain["Drain Engine"] -->|1. Polling Log| MutLog
        Drain -->|2. Resolve file size/meta| USN
        Drain -->|3. Merge UPSERT/DELETE| Facts

        IPC["JSON-RPC Named Pipe Server"]
    end

    subgraph "CLI Tool (disktracker CLI)"
        User["User Interface"] --> CLI["CLI Core Command Dispatch"]
        CLI --> Client["Named Pipe Client Client"]
        Client -->|Named Pipe: \\.\pipe\disktracker| IPC
        
        subgraph "AI Subsystem (disktracker ask)"
            Agent["LangGraph Agent Graph"] -->|Tool Execution| CLI
            Agent -->|ChatModel Engine| LLM["OpenAI / OpenRouter API"]
        end
    end

1. Baseline Scanner: Walks the filesystem on startup (using fast Win32 directory APIs) to index initial facts.
2. USN Watcher Thread: Streams NTFS change events in real-time, instantly logging them into SQLite WAL.
3. Drain Engine: Replays mutation logs, queries file metadata, and merges state into the facts table (transitions from BaselineScanning -> Reconciling -> Live).
4. AI Subsystem: Combines a state graph with 12 built-in CLI and DB tools to allow conversational system diagnostics and file pruning.

📦 Installation

DiskTracker is built for Windows (x64 and ARM64). You can install it through several package managers or a standalone script.

Method 1: Standalone Powershell (Recommended)

Open Command Prompt or PowerShell as Administrator and run:

# Via PowerShell (Admin)
irm https://raw.githubusercontent.com/pratham15541/disktracker/main/install.ps1 | iex

Method 2: NPM Package

npm install -g disktracker

Method 3: Chocolatey

choco install disktracker

Method 4: WinGet

winget install pratham15541.disktracker

🚀 CLI Usage Overview

Below is the quick reference card for DiskTracker commands.

For detailed parameters and flags for each subcommand, read the CLI Command Reference Card.

🤖 The AI Assistant (disktracker ask)

DiskTracker embeds an AI agent powered by LangGraph which operates as a ReAct (Reasoning and Acting) state machine. It is equipped with 12 tools to query and modify system state:

               [User Input]
                    │
                    ▼
          ┌───────────────────┐
          │    Agent Node     │◄───────────────────┐
          └───────────────────┘                    │
                    │                              │
           [Tools Condition Check]                 │
                    │                              │
           Is tool needed?                         │
             /         \                           │
          (Yes)        (No)                        │
           /             \                         │
          ▼               ▼                        │
   ┌─────────────┐   ┌───────────────┐             │
   │ Tools Node  │   │ Final Answer  │             │
   └─────────────┘   └───────────────┘             │
          │                                        │
     [Runs Tool] ──────────────────────────────────┘

The agent is protected by Human-In-The-Loop (HITL) gates. If the AI tries to run a mutating command (such as deleting files or altering snapshots), the CLI pauses, displays the exact script to run, and asks for your explicit permission (y/n).

To read more about the agent tools, prompt structures, and configuration, see AI Agent Guide.

🎯 Next Goals

We plan to expand DiskTracker along these key vectors:

1. Testing Suite Expansion:
   • Write comprehensive E2E tests for the named pipe JSON-RPC interface.
   • Mock NTFS USN Journal logs to test edge cases in our state reducer / drain engine.
   • Run clippy, formatting, and unit tests under GitHub Actions (ci.yml) on every pull request.
2. Cross-Platform Support:
   • Extend the core platform traits with platform-macos utilizing Apple's FSEvents API.
   • Add platform-linux utilizing the Linux inotify system.
3. GUI Desktop Client:
   • Develop a modern, lightweight desktop interface built with Tauri and React.
   • Provide interactive sunburst charts, real-time file modification feeds, and visual timeline analysis.