🤖 DiskTracker AI Orchestrator & LangGraph Integration

DiskTracker integrates an advanced, local LLM-driven AI agent that can converse about your file system state. Built using LangGraph, it enables structured reasoning (via LLMs) combined with deterministic tool execution.

1. Graph State Machine Architecture

The AI subsystem operates as a ReAct (Reasoning and Acting) state machine. It coordinates conversational turns and tool invocations:

stateDiagram-v2
    [*] --> AgentNode : User Prompt
    AgentNode --> RouteCondition : Check response
    RouteCondition --> ToolsNode : If LLM requests tool call
    ToolsNode --> AgentNode : Returns tool execution output
    RouteCondition --> FinalAnswer : If LLM has completed response
    FinalAnswer --> [*]

Agent Node: Formulates a plan based on the conversation history and prompt. It decides whether it has enough information to answer or if it needs to query the system using a tool.
Conditional Routing: Inspects the assistant's message. If tool calls are requested, it routes execution to the Tools Node. Otherwise, it outputs the final response.
Tools Node: Resolves tool parameters, executes the requested system or database tool locally, appends the tool results as a ToolMessage to the graph state, and loops back to the Agent Node.

2. Human-in-the-Loop (HITL) Safety Gates

For safety, tools are classified into Passive (Read-Only) and Active (Mutating):

Passive Tools (e.g. searching the database, checking disk space, running diagnostic commands) execute immediately and transparently.
Active Tools (e.g. deleting files, compressing snapshots, altering configurations) require elevated permissions.
- If the agent attempts a mutating action, the execution pauses.
- The CLI displays the exact command to be executed.
- The user is prompted for approval: Do you want to run this command? (y/n).
- If rejected, a warning is returned to the LLM, and the operation is aborted.

3. Built-In Local System Tools

The agent has access to 12 specialized tools to query or interact with your system:

Tool Name	Type	Description	Parameters
`disktracker_search`	Passive	Searches indexed files (exact substring by default). `advanced` enables multi-tier scoring; `fuzzy` enables typo-tolerant matching (also enables advanced).	`query` (string), `path` (string), `ext` (string), `min_size` (int), `max_size` (int), `modified_after` (string), `modified_before` (string), `advanced` (bool), `fuzzy` (bool), `limit` (int)
`disktracker_history`	Passive	Queries mutation history. Created/Deleted/Renamed always shown (incl. 0B); Modified only if `	size_delta
`disktracker_top`	Passive	Ranks by size, growth, or churn. Growth: 0B create/delete can appear; tiny non-zero growth under 2B is hidden.	`path` (string), `volume` (string), `folders` (bool), `files` (bool), `since` (string), `between_a` (string), `between_b` (string), `growth` (bool), `churn` (bool), `limit` (int)
`sqlite_read_query`	Passive	Runs arbitrary read-only SQL queries directly against the index database.	`query` (string)
`cli_read_command`	Passive	Runs safe, read-only system shell commands (e.g. `dir`, `df`, `cat`) to verify OS state.	`command` (string)
`disktracker_status`	Passive	Queries the status of the local DiskTracker daemon and active volumes.	(none)
`disktracker_doctor`	Passive	Diagnoses database health and recent operations logs.	(none)
`disktracker_snapshot_list`	Passive	Lists saved snapshots in the database.	`volume` (string), `limit` (int)
`disktracker_snapshot_diff`	Passive	Diffs files between two snapshots. Created/Deleted/Renamed always shown (incl. 0B); Modified only if `	size_delta
`fetch_signature`	Passive	Resolves heuristics and signatures for directories or executables (e.g. `System32`, `Temp`).	`target` (string)
`cli_write_command`	Active	Executes a file-mutating OS command (e.g. `rm`, `del`, `erase`). Triggers HITL prompt.	`command` (string)
`snapshot_manage`	Active	Deletes or compresses a saved snapshot. Triggers HITL prompt.	`action` (string), `label` (string)

4. Configuration and Credentials

Credentials and API keys are stored securely using Windows Credential Manager via the keyring crate. They are never saved in plain text files.

Set up OpenAI/OpenRouter connection:

# Configure endpoint base URL
disktracker ai config --base-url "https://openrouter.ai/api/v1"

# Set model name
disktracker ai config --model "meta-llama/llama-3-70b-instruct"

# Commit API token securely
disktracker ai config --api-key "your-api-key-here"

Test API Handshake

Verify that DiskTracker can communicate with your LLM provider:

disktracker ai test

Conversational Session History

You can manage and view previous conversational sessions:

# List all saved sessions
disktracker ai session list

# Show the full chat transcript of a session
disktracker ai session show <session-id>

DiskTracker Documentation