Windows Shortcut

Overview

Lets the agent build the same kind of desktop shortcut you'd create by right-clicking 'New → Shortcut' — a .lnk file that double-clicks to launch a program with optional args and an icon. Useful for setting up a user's environment, pinning a discovered tool to the desktop, or auditing what shortcuts already exist in a folder.

How it works

Three operations: list (enumerate .lnk files under a path with their target), inspect (read a single .lnk's target/args/working-dir/icon/description/hotkey), create (write a new .lnk via WScript.Shell). The .lnk file path is checked against the allowlist; the embedded target is not (a desktop shortcut routinely targets C:\Program Files\…\app.exe). Pass apply=true to actually write the .lnk; otherwise the tool returns a dry-run plan.

Example

When a user asks:

Pin Notepad to the desktop with custom args.

the agent calls the tool:

windows_shortcut(operation="create", path="C:/Users/me/Desktop/My Notepad.lnk", target="notepad.exe", args="todo.txt", apply=true)

and gets back: an approval prompt, then a new .lnk on the desktop that launches Notepad with todo.txt.

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.

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

Allowlisted folders the .lnk file itself may live in. The shortcut's stored target may point anywhere on disk.

swarmai.tools.windows.auto-approve optional

Skip the y/N prompt for shortcut writes. 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

# pin-tools.yaml
name: pin-tools-crew
process: SEQUENTIAL

agents:
  - id: organiser
    role: Desktop Organiser
    goal: Pin frequently-used tools to the desktop as labelled shortcuts
    tools:
      - windows_shortcut

tasks:
  - id: pin-task
    agent: organiser
    description: Create a Notepad shortcut with the user's todo file as an argument.

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.WindowsShortcutTool;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.beans.factory.annotation.Autowired;

@Autowired ChatClient chatClient;
@Autowired WindowsShortcutTool windowsShortcutTool;

Agent organiser = Agent.builder()
    .role("Desktop Organiser")
    .goal("Pin frequently-used tools to the desktop as labelled shortcuts")
    .chatClient(chatClient)
    .tool(windowsShortcutTool)
    .build();

Task organiserTask = Task.builder()
    .description("Create a Notepad shortcut on the desktop pointing at todo.txt.")
    .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.

Set up a developer's machine by pinning frequently-used tools to the Desktop

Audit what .lnk files already exist in Start Menu / Desktop folders

Replace a broken shortcut after the agent reorganized a target folder

Pair with windows_filesystem for end-to-end 'install + pin' workflows

Source

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

Open windows_shortcut on GitHub →