> ## Documentation Index
> Fetch the complete documentation index at: https://docs.swarms.world/llms.txt
> Use this file to discover all available pages before exploring further.

# Autonomous Looper with Bash

> Run an autonomous agent loop that can execute bash commands to complete long-horizon tasks.

Use the **`run_bash`** tool so an autonomous agent can run shell commands on the terminal.

## When to use it

* The agent needs to run CLI commands (e.g. `ls`, `python script.py`, `git status`).
* You use `max_loops="auto"` and want the agent to have terminal access.
* You want to keep other tools restricted and only add bash execution.

## Enable the tool

Include `"run_bash"` in `selected_tools` when creating the agent:

```python theme={null}
from swarms import Agent

agent = Agent(
    agent_name="Terminal-Agent",
    agent_description="Agent that can run bash commands on the terminal",
    model_name="anthropic/claude-sonnet-4-6",
    max_loops="auto",
    dynamic_context_window=True,
    selected_tools=[
        "create_plan",
        "subtask_done",
        "complete_task",
        "respond_to_user",
        "read_file",
        "list_directory",
        "run_bash",
    ],
)
```

## Run a task

The agent will plan and call `run_bash` when it needs to run a command:

```python theme={null}
result = agent.run(
    task="Use the terminal to list the current directory, then run 'echo Hello from bash' and report the output."
)
print(result)
```

## Tool parameters

| Parameter | Type | Description |
| - | - | - |
| `command` | string | The bash/shell command to run (e.g. `ls -la`, `python script.py`). |
| `timeout_seconds` | integer | (Optional) Max seconds to wait; default is 60. |

Commands run in the Python process's current working directory, not the agent workspace. The tool returns the exit code, stdout and stderr. Long-running commands should use a higher `timeout_seconds` or be avoided.

## Limits and safety checks

* **Length**: commands over 512 characters are refused. If the command is a heredoc or redirect, the refusal tells the model to write the file with `create_file` or `update_file` instead, so give the agent those tools when it needs to write files.
* **Blocklist**: commands matching dangerous patterns are refused, including recursive `rm`, piping into a shell or interpreter, `sudo`, shutdown and reboot, `printenv`, `curl -d`, redirects into `/etc` or `/usr`, and redirects to disk devices or `/dev/null`.
* **Output cap**: the result is capped at a quarter of the agent's `context_length` in tokens, with a marker saying how much was cut. Set `context_length` lower for a tighter cap.
* **Searches**: for finding files or matching text, the `glob` and `grep` tools are preferred over `find` and `grep` through bash.

<Warning>
  The blocklist is a guard, not a sandbox. The command runs with your process's permissions. Run untrusted tasks in a container or a throwaway working directory.
</Warning>

## Example file

A starting-point script is in the repo. It builds this agent and prints the available tool names; uncomment the `agent.run(...)` call to run a task:

```
examples/single_agent/capabilities/autonomy/autonomous_agents/example_autonomous_looper_run_bash.py
```

## See also

* [Autonomous Looper Tools](/examples/agents/autonomous-looper-tools) – Configuring `selected_tools`
* [Autonomous Mode](/agents/autonomous-mode) – How the loop plans, runs tools and stays bounded
* [Agent Reference](/api/agent) – `selected_tools` and autonomous loop


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.