Shell Command

Overview

Lets the agent run a limited, pre-approved set of safe commands to inspect the computer it's running on — things like listing files or checking git status. Nothing that could change your system, just looking around.

How it works

Runs the supplied command against a whitelist of read-only utilities — ls, cat, grep, git (read), ps, df, du, head, tail, wc, find, echo, pwd, env, date — with a configurable timeout (default 120s, hard cap 300s). Pipes and output redirection ('>', '>>') are blocked to prevent arbitrary file writes.

Example

When a user asks:

Show me the last 5 commits on this branch.

the agent calls the tool:

shell_command(command="git log --oneline -5")

and gets back: the commit hashes and subject lines from git log.

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

# ops-inspection.yaml
name: ops-inspection-crew
process: SEQUENTIAL

agents:
  - id: inspector
    role: Ops Inspector
    goal: Inspect the runtime environment safely
    tools:
      - shell_command

tasks:
  - id: ops-inspection-task
    agent: inspector
    description: Show the last 5 commits on the current branch via git log.

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

@Autowired ChatClient chatClient;
@Autowired ShellCommandTool shellCommandTool;

Agent inspector = Agent.builder()
    .role("Ops Inspector")
    .goal("Inspect the runtime environment safely")
    .chatClient(chatClient)
    .tool(shellCommandTool)
    .build();

Task inspectorTask = Task.builder()
    .description("Show the last 5 commits on the current branch via git log.")
    .agent(inspector)
    .build();

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

What it's good for

Real scenarios where agents put this tool to work.

Source

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

Open shell_command on GitHub →