OS Process

Overview

The platform-agnostic process tool. Same surface on every OS; the backend dispatches to ps/kill on macOS and Linux and to ProcessHandle on Windows. System processes are denylisted at the configuration level, so an over-eager agent can't accidentally kill kernel_task, systemd, or winlogon.

How it works

Three operations: list (filter by name substring), start (launch via 'open -a' on macOS, xdg-open on Linux, direct exec on Windows), kill (by PID or name; resolves the name for the denylist check first). Mutations route through the same MutationGuard + ApprovalGateHandler + AuditLogger pipeline as the filesystem tool. The denylist defaults to a union covering all three OSes' system processes.

Example

When a user asks:

Kill the Spotify process if it's running.

the agent calls the tool:

os_process(operation="kill", name="Spotify", apply=true)

and gets back: a confirmation that the process was killed (or denied if 'spotify' had been added to the denylist).

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 category (shared with os_filesystem).

swarmai.tools.os.process.denylist optional

Comma-separated process names that may never be killed regardless of approval. Default union covers Windows (system, smss, csrss, winlogon, …), macOS (kernel_task, launchd, WindowServer, …), Linux (systemd, init, kthreadd).

swarmai.tools.os.process.timeout optional

Per-invocation timeout for 'ps' lookups on POSIX. Default 15s.

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

# process-watch.yaml
name: process-watch-crew
process: SEQUENTIAL

agents:
  - id: watcher
    role: Process Watcher
    goal: Inspect what's running and act on user requests
    tools:
      - os_process

tasks:
  - id: watch-task
    agent: watcher
    description: List the top processes by name, then kill anything the user asks to terminate.

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

@Autowired ChatClient chatClient;
@Autowired ProcessTool osProcessTool;

Agent watcher = Agent.builder()
    .role("Process Watcher")
    .goal("Inspect what's running and act on user requests")
    .chatClient(chatClient)
    .tool(osProcessTool)
    .build();

Task watch = Task.builder()
    .description("List the top processes; kill anything the user asks to terminate.")
    .agent(watcher)
    .build();

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

What it's good for

Real scenarios where agents put this tool to work.

Cross-platform 'what's running on my machine?' diagnostics

Stop a hung renderer process from a chat prompt without changing the prompt per-OS

Monitor a long-running compute job and surface progress to the agent

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

Source

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

Open os_process on GitHub →