# SwarmAgency

An open-source multi-agent AI team, forked from [OpenSwarm](https://github.com/VRSEN/OpenSwarm) and rebranded as **SwarmAgency**.

Eight specialist agents coordinated by an orchestrator, running in your terminal.

## What you get

| Agent | What it does |
|-------|--------------|
| Orchestrator | Routes every request to the right specialist(s). Never answers directly. |
| Virtual Assistant | Writing, scheduling, messaging, 10,000+ integrations via Composio. |
| Deep Research | Evidence-based web research with citations. |
| Data Analyst | Structured-data analysis, charts, statistical models in an IPython kernel. |
| Slides Agent | HTML slide decks exported to PPTX. |
| Docs Agent | Formatted Word documents and PDFs. |
| Image Generation | Gemini 2.5/3 Pro, gpt-image-1.5, background removal. |
| Video Generation | Sora, Veo, Seedance 1.5 Pro. |

## Install

```bash
npm install -g @vrsen/openswarm
swarmagency
```

On first run the setup wizard asks for a provider API key, a default model, and any optional add-ons (Composio, Gemini image gen, Fal.ai, stock photos).

If you cloned this repo directly:

```bash
git clone https://github.com/VRSEN/OpenSwarm
cd openswarm
npm install
python swarmagency.py
```

`python swarmagency.py --onboard` runs the wizard explicitly.

## Run

Three equivalent entry points:

| Command | What it does |
|---------|--------------|
| `swarmagency` | Global command (after `npm install -g`). Spawns the TUI via the Node launcher. |
| `python swarmagency.py` | Python entry. Spawns the TUI; on first run, also prompts to pick a model. |
| `bin/swarmagency` | Local Node wrapper that delegates to `bin/openswarm`. |

The TUI lets you pick an agent, chat, and switch agents mid-session. **The model itself is fixed for the session** — switching model requires quitting and re-launching with `--model`.

## Model selection

SwarmAgency supports multiple providers. The interactive picker shows up:

- On first run, if no `DEFAULT_MODEL` is in `.env`
- Whenever the TUI posts the model-switch flag file back to Python (e.g. you choose "Switch model" in the TUI)

To set a model without the picker:

```bash
python swarmagency.py --model deepseek/deepseek-v4-flash
python swarmagency.py --model minimax/MiniMax-M3
python swarmagency.py --model minimax/MiniMax-M2.7-highspeed
```

The argument is a `<provider>/<model>` ID written to `DEFAULT_MODEL` in your `.env` file.

**Supported providers** (each requires its own API key add-on):

| Provider | Env var | Default model | Notes |
|----------|---------|---------------|-------|
| Deepseek | `DEEPSEEK_API_KEY` | `deepseek/deepseek-v4-flash` | Free / cheap reasoning models |
| Minimax | `MINIMAX_API_KEY` | `minimax/MiniMax-M3` | Fast, cost-effective |
| OpenAI | `OPENAI_API_KEY` | (no direct model ID — uses litellm routing) | Codex browser auth is **not** supported for media endpoints (images/video). |
| Anthropic | `ANTHROPIC_API_KEY` | (litellm routing) | Add-on only — better slide output quality. |
| Google Gemini | `GOOGLE_API_KEY` | (litellm routing) | Required for image/video generation. |
| Fal.ai | `FAL_KEY` | — | Seedance video, background removal. |
| Ollama | — | any `ollama list` model | Local free models only. |
| OpenRouter | `OPENROUTER_API_KEY` | `:free` suffix required | Free tier only. |

## Configuration

All configuration lives in a single `.env` file:

| OS | Path |
|----|------|
| Windows | `%APPDATA%\SwarmAgency\.env` |
| macOS / Linux | `~/.swarmagency/.env` |

Override with `OPENSWARM_STATE_ROOT=/path/to/folder` (the env var name is kept for backward compatibility).

If you previously installed OpenSwarm, the existing `~/.openswarm/.env` (or `%APPDATA%\OpenSwarm\.env`) is still picked up on first launch under the new name — SwarmAgency prefers the new `SwarmAgency/` folder, falls back to the legacy `OpenSwarm/` folder.

## Honest limitations

- **No mid-session model hot-swap.** Changing model requires a fresh launch. The "Switch model" TUI option just restarts the picker.
- **Two providers in the picker.** The interactive selector only shows Deepseek and Minimax — these are the direct providers we have full model lists for. Other providers (OpenAI, Anthropic, Google) are reached via litellm routing and use the `DEFAULT_MODEL` from the wizard.
- **State-root migration is one-way.** SwarmAgency writes to the new `SwarmAgency/` folder, but if `OpenSwarm/` already exists, it keeps using that. To force a clean migration, move/rename the folder manually.
- **Forked from OpenSwarm 1.0.1-rc.7.** The Node launcher, TUI engine, and `@vrsen/openswarm-cli-*` platform packages are still from upstream. The rebrand is at the Python + Node config layer.

## Local development

```bash
# Run with the model picker forced (no --model arg)
python model_selector.py

# Launch the TUI directly (skips the picker if DEFAULT_MODEL is set)
python swarm.py

# Run a specific model without the picker
python swarmagency.py --model deepseek/deepseek-v4-pro

# API server (for embedding the agency in another app)
python server.py            # localhost:8080
```

## Architecture

Two entry points, three layers:

1. **Node launcher** (`bin/openswarm` / `bin/swarmagency`) — resolves the TUI binary from `@vrsen/openswarm-cli-<platform>-<arch>`, spawns it with `AGENTSWARM_LAUNCHER=1` and the product env vars from `openswarm.config.mjs`.
2. **TUI engine** (`@vrsen/agentswarm` v1.4.37-rc.1) — the terminal UI; the user picks an agent and chats.
3. **Python agency** (`swarm.py` → `run_utils.py`) — the actual agents. The TUI shells out to Python to run them.

```
bin/swarmagency ──► bin/openswarm ──► agentswarm (TUI) ──► python swarm.py
                                                              │
                                                              └─► run_utils.main (loop)
                                                                      │
                                                                      └─► create_agency() → agency.tui()
```

## License

MIT — see [LICENSE](LICENSE).
