# OpenSwarm: a multi-agent terminal team for slide decks, research and video

> OpenSwarm is an MIT-licensed Python multi-agent system built on Agency Swarm that routes one prompt to eight specialist agents. It installs through npx, runs on Python 3.12 and Node.js 20, and needs at least one model API key.

**VRSEN/OpenSwarm** — Claude code for everything except coding

- Repository: https://github.com/VRSEN/OpenSwarm
- Stars: 2,860 · Forks: 670
- Language: Python
- License: MIT
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/vrsen-openswarm

## What OpenSwarm does that a single chat agent does not

The README frames the project as "the fully open-source multi-agent system that does everything Claude Code can't", and the deliverables it lists are slides, research reports, data visualizations, documents, images and videos. The intended user is someone working from a terminal who wants a finished artifact rather than a conversation: the examples in the README include an investor pitch that returns a deck plus an executive summary and market research, and a competitor study that returns analysis plus three blog posts. That is a different shape of task from code editing. The output is a file or a set of files, and the work is split across roles rather than done by one model in one context window. The repository is MIT licensed and the package metadata describes it as "An open-source multi-agent AI team built on Agency Swarm". If your work is source code, this is not aimed at you. If your work is decks, reports and media, it is.

## The orchestrator plus eight specialists architecture

OpenSwarm is not a single agent with a long tool list. The README describes an Orchestrator that "routes every user request to the right specialist(s)" and "never answers directly". The specialists are separate: a Virtual Assistant for writing, scheduling and messaging; a Deep Research agent for web research with citations; a Data Analyst that works inside an isolated IPython kernel; a Slides agent that builds HTML decks and exports them to PPTX; a Docs agent for Word and PDF output; an Image Generation agent; and a Video Generation agent. The repository layout matches this, with one directory per agent at the top level (orchestrator/, deep_research/, data_analyst_agent/, slides_agent/, docs_agent/, image_generation_agent/, video_generation_agent/, virtual_assistant/) alongside shared_tools/ and a shared_instructions.md. That layout is the practical argument for the design: because each agent is a folder with its own instructions and tools, you can change one specialist without touching the routing layer. The cost is that a request crossing three roles passes through three sets of instructions, and the README does not document how much context is carried between them.

## Installing OpenSwarm and running a first deck

The README gives a one-line install through npm. It states that the setup wizard handles authentication, dependencies and configuration, and that the requirements are Node.js 20+ and Python 3.12+. OpenSwarm "creates or repairs an isolated project .venv" according to the same section.

```bash
npx @vrsen/openswarm
```

After the wizard finishes you should be at a terminal prompt inside the swarm. The README's own example prompt, quoted here, is the shortest way to see the Slides agent work end to end:

```bash
Create a complete investor pitch for OpenSwarm
```

According to the README this returns a full deck, an executive summary and market research. If you would rather run the swarm from a clone, the developer section gives two more entry points. The first runs the swarm directly, and the second starts the API server on port 8080:

```bash
python swarm.py
python server.py
```

For a container deployment the README documents copying the example environment file, adding keys, and building with Compose. The Compose file maps port 8080 and mounts ./mnt and ./uploads into the container:

```bash
cp .env.example .env
docker-compose up --build
```

On keys, the README is explicit that you need at least one of OPENAI_API_KEY or ANTHROPIC_API_KEY, and that COMPOSIO_API_KEY, GOOGLE_API_KEY, FAL_KEY and SEARCH_API_KEY are optional. Telemetry can be turned off with ENABLE_TELEMETRY=0, OPEN_SWARM_TELEMETRY=0 or AGENTSWARM_TELEMETRY=0, or with the --no-telemetry flag.

## Where OpenSwarm stops short

The honest limitation is in the README's own sentence: "Tools gracefully degrade when keys are missing." Graceful degradation is a reasonable design, but it means the agent you asked for may not be the agent you get. Ask for a video with only an OpenAI key and the Video agent's Sora path is available while the Google Veo and fal.ai Seedance paths are not, because the README lists GOOGLE_API_KEY and FAL_KEY as the credentials for those. Ask for image generation without GOOGLE_API_KEY and the Gemini image path the README names is unavailable. The wizard will tell you what to add, but the deliverable is still incomplete. There is a second boundary: the README describes the system as running "in your terminal" with "no platform, no UI", so anyone expecting a web dashboard or a hosted endpoint has the wrong product. The third is environmental. The Python project pins agency-swarm[fastapi,jupyter,litellm]==1.10.5 and composio==0.15.0, and the dependency list pulls in weasyprint, playwright, opencv-python-headless and moviepy<2. Those are heavy native dependencies, and the README does not document what happens when one of them fails to build on your platform.

## OpenSwarm compared with AgentSwarm and Agency Swarm

The README points to two related projects from the same organisation, and the difference is worth stating plainly. Agency Swarm is described as the multi-agent framework underneath; it is the layer you would use to define agents, tools and handoffs yourself. AgentSwarm is described as a "Terminal UI for Agency Swarm (OpenCode-based TUI)", meaning it supplies a terminal interface over the framework. OpenSwarm sits above both as a ready-made team: eight named agents, a set of shared tools, and a wizard that installs the runtime. Choosing between them is choosing how much you want to build. If you want a specific swarm for a specific workflow, Agency Swarm gives you the primitives and OpenSwarm gives you a working example to fork. If you want a different terminal experience over your own agents, AgentSwarm is the interface project. The trade-off is that OpenSwarm's opinions, such as the orchestrator that never answers directly, come bundled with the convenience.

## Forking OpenSwarm into your own swarm

The README's customisation path is deliberately low-tech: clone the repository and then ask an external coding assistant to restructure it. The quoted instruction is to tell Claude Code, Cursor or Codex to "Turn this into an SEO optimization swarm". The README lists SEO, sales, marketing and product swarms as popular directions. This works because the agent definitions live in ordinary directories rather than in a compiled artifact, and the shared tools sit in shared_tools/ with shared_instructions.md alongside. It is also the weakest documented part of the project. There is no specification for what a valid agent directory must contain, no schema for the handoff between specialists, and no test harness described in the README for checking that a modified swarm still routes correctly. The tests/ directory exists in the repository, but the README does not explain what it covers. Treat forking as editing prompts and tools under version control, and expect to read the existing agent folders before you can trust a rewrite.

## Licence, maintenance and upgrade cost

OpenSwarm is MIT licensed, and both package.json and pyproject.toml carry the MIT identifier. In practical terms that permits commercial use, modification and redistribution provided the copyright notice and licence text are kept, but the usual caveat applies: the repository contains no statement about the licences of the models or third-party services it calls, and Composio, fal.ai, Google and OpenAI each have their own terms. Nothing here is legal advice; if you ship OpenSwarm inside a product, review those separately. On maintenance, the repository is not archived and the last push was on 2026-07-26, with releases v1.1.3, v1.1.2 and v1.1.1 all landing in July 2026. The upgrade cost is concentrated in two pins: agency-swarm==1.10.5 and composio==0.15.0, both exact rather than ranged. That buys reproducibility and makes a future bump a deliberate act, because agency-swarm carries the fastapi, jupyter and litellm extras the agents rely on. The npm side pins @vrsen/agentswarm 1.4.43 and dom-to-pptx 1.1.5, and the postinstall script applies a patch to dom-to-pptx through patch-package, which is the piece most likely to break when that dependency moves.

## Conclusion

Adopt OpenSwarm if you already hold an OpenAI or Anthropic key and want generated decks, documents, charts or clips without wiring each tool yourself; the npx wizard and the Docker path both exist, and the MIT licence lets you fork the agent folders. Do not adopt it if you need a stable hosted service, a graphical interface, or guaranteed output from every agent on a single key, because the README states that tools degrade when optional keys are absent. Before committing, run the install once and confirm which agents actually respond with the keys you own, and check whether your Python environment can hold the pinned agency-swarm 1.10.5 and composio 0.15.0 versions.

## FAQ

### How do I install OpenSwarm?

The README gives a single command, npx @vrsen/openswarm, and states that the setup wizard handles authentication, dependencies and configuration. It requires Node.js 20+ and Python 3.12+, and creates or repairs an isolated project .venv.

### What is OpenSwarm?

It is an open-source multi-agent system built on Agency Swarm that produces slide decks, research reports, data visualizations, documents, images and videos from a single terminal prompt. The README describes eight specialized agents coordinated by an orchestrator.

### Is OpenSwarm free?

The project is MIT licensed, so the code is free to use and fork. The models and services it calls are not part of that licence, and the README requires at least one of OPENAI_API_KEY or ANTHROPIC_API_KEY before the agents can run.

### Does OpenSwarm use AI?

Yes. It is built on Agency Swarm and the OpenAI Agents SDK, and the README lists OpenAI, Anthropic, Google Gemini, Sora, Veo and fal.ai as the model backends behind its agents.

### How does OpenSwarm work?

An Orchestrator routes each request to one or more specialists, which include a Virtual Assistant, Deep Research, Data Analyst, Slides, Docs, Image Generation and Video Generation agent. Each agent is a separate directory in the repository with its own instructions and tools.

## Sources

- [Issues](https://github.com/VRSEN/OpenSwarm/issues)
- [License: MIT](https://github.com/VRSEN/OpenSwarm/blob/main/LICENSE)
- [README](https://github.com/VRSEN/OpenSwarm/blob/main/README.md)
- [Releases](https://github.com/VRSEN/OpenSwarm/releases)
- [VRSEN/OpenSwarm on GitHub](https://github.com/VRSEN/OpenSwarm)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/vrsen-openswarm