Windows Filesystem

Overview

Lets the agent tidy or reorganize files on a real Windows machine — list a folder, then move, copy, rename, delete, or create directories. The agent only ever sees folders you allowlisted, and every change is presented to you for y/N approval before it runs.

How it works

Read ops (list) execute immediately. Mutations (move, copy, rename, delete, mkdir) build a MutationPlan and are routed through SupervisedMutationGuard / ConsoleApprovalGateHandler — by default each plan prints to stderr and waits for y/N on stdin. Paths outside the configured allowlist roots are rejected. Recursive directory move/delete is refused in v1. Pass apply=true to execute; otherwise the tool returns a dry-run plan.

Example

When a user asks:

Tidy my Desktop — move loose PDFs into Documents and ZIPs into Archives.

the agent calls the tool:

windows_filesystem(operation="move", from="C:/Users/me/Desktop/budget.pdf", to="C:/Users/me/Desktop/Documents/budget.pdf", apply=true)

and gets back: either an approval prompt followed by the moved-file confirmation, or a dry-run plan if apply was omitted.

Configuration

Set these before calling the tool. Values marked required must be present or the tool call will fail.

swarmai.tools.windows.enabled required

Master switch for the Windows tool category. Must be true; defaults to false so non-Windows builds aren't surprised.

swarmai.tools.windows.filesystem.allowed-roots optional

List of allowlisted root folders. Any path outside these is refused. Defaults to ${user.home}/Desktop, ${user.home}/Downloads, ${user.home}/Documents.

swarmai.tools.windows.filesystem.dry-run-default optional

When true (default), mutations require explicit apply=true on the call.

swarmai.tools.windows.auto-approve optional

Skip the y/N prompt and auto-approve every mutation. Intended for non-interactive runs only.

Use it in a workflow

Wire this tool into a SwarmAI crew. Use the YAML DSL for declarative workflows, or the Java builder API when you want full programmatic control.

YAML DSL

# desktop-tidy.yaml
name: desktop-tidy-crew
process: SEQUENTIAL

agents:
  - id: organiser
    role: Desktop Organiser
    goal: Sort loose files on the Desktop into category folders
    tools:
      - windows_filesystem

tasks:
  - id: desktop-tidy-task
    agent: organiser
    description: List the Desktop, propose Apps/Documents/Images/Videos/Archives/Misc folders, and move loose files into the right one.

Java

import ai.intelliswarm.swarmai.agent.Agent;
import ai.intelliswarm.swarmai.task.Task;
import ai.intelliswarm.swarmai.swarm.Swarm;
import ai.intelliswarm.swarmai.swarm.SwarmOutput;
import ai.intelliswarm.swarmai.process.ProcessType;
import ai.intelliswarm.swarmai.tool.windows.WindowsFileSystemTool;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.beans.factory.annotation.Autowired;

@Autowired ChatClient chatClient;
@Autowired WindowsFileSystemTool windowsFileSystemTool;

Agent organiser = Agent.builder()
    .role("Desktop Organiser")
    .goal("Sort loose files on the Desktop into category folders")
    .chatClient(chatClient)
    .tool(windowsFileSystemTool)
    .build();

Task organiserTask = Task.builder()
    .description("List the Desktop, propose category folders, and move loose files into the right one.")
    .agent(organiser)
    .build();

SwarmOutput result = Swarm.builder()
    .agent(organiser)
    .task(organiserTask)
    .process(ProcessType.SEQUENTIAL)
    .build()
    .kickoff();

What it's good for

Real scenarios where agents put this tool to work.

Tidy a user's Desktop or Downloads folder by category

Reorganize project folders with explicit human approval per move

Bulk-rename or copy files inside allowlisted paths

Dry-run plans for what an agent would do before granting apply

Source

Implementation lives at swarmai-tools/src/main/java/ai/intelliswarm/swarmai/tool/windows/WindowsFileSystemTool.java in the swarm-ai repository.

Open windows_filesystem on GitHub →