OS Filesystem

Overview

The platform-agnostic filesystem tool. Pick a directory inside the allowlist and the agent can list, stat, mkdir, copy, move, rename, delete, write_text, or append_text — the same operations on every OS, with the same approval gate guarding mutations. Replaces the per-OS variants for everything except shortcut/screenshot/window control.

How it works

Implements the standard read + mutate operations against java.nio.file with PathGuard allowlisting and a kill-switch + audit + approval guard chain. The tool's metadata declares os: [windows, darwin, linux] so the framework's pre-flight checker accepts it on any host. Every mutating op runs in plan-only mode unless apply=true is passed; passing apply=true still routes through the configured ApprovalGateHandler (console y/N by default).

Example

When a user asks:

Tidy my Downloads folder by category.

the agent calls the tool:

os_filesystem(operation="list", path="~/Downloads")  → os_filesystem(operation="mkdir", path="~/Downloads/Images", apply=true)  → os_filesystem(operation="move", path="~/Downloads/photo.jpg", to="~/Downloads/Images/photo.jpg", apply=true)

and gets back: a directory listing followed by approved mkdir + move operations, each cited and audit-logged.

Configuration

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

swarmai.tools.os.enabled required

Master switch for the cross-platform OS-control tool category. Off by default so deployments that don't want filesystem mutations stay clean.

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

Comma-separated list of allowed root directories. ${user.home} expands per-OS; the same config works on Windows, macOS, and Linux. Defaults to ~/Desktop, ~/Downloads, ~/Documents.

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

When true (default), mutating ops require apply=true to actually run. Useful for first-time deployments to see plans before any side effects.

swarmai.tools.os.auto-approve optional

Skip the y/N approval prompt — every mutation auto-approves. Audit log + kill switch still apply. Demo / unattended use 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: Group loose files into category folders
    tools:
      - os_filesystem

tasks:
  - id: tidy-task
    agent: organiser
    description: Inspect ~/Downloads, propose a small set of category folders, then move every loose file 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.os.FileSystemTool;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.beans.factory.annotation.Autowired;

@Autowired ChatClient chatClient;
@Autowired FileSystemTool osFileSystemTool;

Agent organiser = Agent.builder()
    .role("Desktop Organiser")
    .goal("Group loose files into category folders")
    .chatClient(chatClient)
    .tool(osFileSystemTool)
    .build();

Task tidy = Task.builder()
    .description("Inspect ~/Downloads, propose categories, move loose files into them.")
    .agent(organiser)
    .build();

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

What it's good for

Real scenarios where agents put this tool to work.

Cross-platform 'tidy my Downloads' agent that runs identically on every OS

Periodic content-aware sorting via a scheduled crew

RAG document-staging pipelines that move processed PDFs into an indexed folder

Replace per-OS filesystem tool variants with one declarative tool the LLM can pick

Source

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

Open os_filesystem on GitHub →