Skip to main content

Documentation Index

Fetch the complete documentation index at: https://agency-swarm.ai/llms.txt

Use this file to discover all available pages before exploring further.

Agent Swarm TUI is the terminal UI for Agency Swarm. Use it when you want to build or test your Agency Swarm project in the terminal.

​
Start the TUI

For most users, the right way to start is: 
npx @vrsen/agentswarm
This is the main launch path. It handles first-run setup, then connects the terminal UI to your Agency Swarm server. Run it from your project root. If you are starting fresh, run it in a new empty folder. You do not need to install the TUI globally first. Agent Swarm TUI startup screen

​
Before You Start

Make sure you have:
  • Node.js installed so npx is available
  • Python 3.12 or newer available for Agency Swarm projects
  • a model provider credential if you want to send prompts right away, or you can add it later with /auth
  • an existing agency project, or a starting point from From Scratch or the Starter Template

​
What Happens on First Launch

On first launch, you will usually see this flow:
1

Start the launcher

Start with npx @vrsen/agentswarm.
2

Point the launcher at an agency

The launcher can reuse the current Agency Swarm project, create a starter project, or connect to an agency that is already running.
3

Set up the project environment

The launcher checks for a project .venv. If it needs to create one, it asks first and then installs the project dependencies before opening the TUI.
4

Open the TUI and add auth if needed

The TUI opens connected to your agency. If you do not already have a usable model provider configured, use /auth.
This is the path we recommend for onboarding, videos, and first-time users.

​
What You Can Do in the TUI

Once the TUI is running, you get:
  • a keyboard-first terminal workflow
  • session history, export, undo, redo, and /compact
  • /agents to switch between top-level agents
  • @AgentName mentions to route a prompt to a specific top-level agent
  • @ file and resource references to attach local or MCP context in the same prompt flow
  • Tab autocomplete for both agent mentions and file and resource references
  • direct access to local project files for prompt context
Agent Swarm TUI agent picker

​
Optional Paths

If this is your first run, you can ignore everything below.
Use the same npx @vrsen/agentswarm command, then choose Connect to a running agency during onboarding.This is the optional /connect path.The launcher asks for:
  1. the Agency Swarm base URL
  2. whether the server needs a bearer token
  3. the agency id, if automatic discovery does not already find it
Use it when:
  • a local Agency Swarm server is already running
  • you want to connect to a remote Agency Swarm server
  • the server is protected and needs a bearer token
Current limitations for this path:
  • /models does not switch the models configured inside your Agency Swarm backend yet
  • local file tools are not available; if you want the TUI to work directly on project files, start with npx @vrsen/agentswarm from that project directory instead
Use your Python config to choose backend models and providers.
If your project already launches from Python, agency.tui() still works as the secondary entrypoint.
agency.tui()
Then start your project the usual way:
python agency.py
This path stays bound to the exact Agency instance you passed in Python. It starts the local bridge for that agency, then opens the TUI connected to it.Use it when your team already starts the project from Python and you want a quick TUI test path without switching directories or changing entrypoints.
tui(show_reasoning=False) is not supported in the new TUI yet.