# Run Modes

Morphy can tackle a task with a single agent or with many agents working together. Choose the
mode that fits the size of the job.

| Mode | Best for |
| --- | --- |
| **Agent** (default) | Most tasks — one focused agent with all tools |
| **Subagents** | Work that splits into independent parallel pieces |
| **Swarm** | Large, open‑ended builds that benefit from coordinated roles |

## Agent (default)

A single agent plans and executes with the full toolset (file editing, shell, search, web,
and more). This is what you get by default in interactive and one‑shot mode.

```bash
morphy "fix the failing test in this project"
```

## Subagents

Morphy spawns several lightweight agents that run independent subtasks in parallel, each with
its own isolated workspace, then brings the results back together. Great for fan‑out work like
touching many files or exploring several options at once.

```bash
morphy --run subagents -a 6 "add docstrings to every public function"
```

- `-a, --agents <n>` — how many parallel agents
- `-c, --cycles <n>` — maximum work cycles

## Swarm

Swarm mode coordinates many agents with distinct **roles** — architect, scout, worker,
reviewer, integrator — to take on large, end‑to‑end tasks such as building an application from
a single prompt.

From the shell:

```bash
morphy --run swarm -a 8 "build a REST API for a todo app with tests"
```

From the interactive interface:

```
/swarm build a REST API for a todo app with tests
```

Tune the size with `-a/--agents` (number of agents) and `-c/--cycles` (maximum cycles).
Larger numbers can handle bigger tasks but use more time and tokens.

## Keeping costs in check

Any mode accepts a spending cap. Morphy stops once the known LLM cost reaches the limit:

```bash
morphy --run swarm --budget 5 "..."
```

Use `/cost` during an interactive session to watch token and cost usage live.