ts-demo

<img src="doc_en/banner.svg" alt="OpenSquad" width="720" />

<strong>English</strong> | <a href="README_ZH.md">中文</a>

OpenSquad is a local-first multi-agent collaboration framework. Multiple autonomous agents (PM, Coder, QA, etc.) communicate via group chat to coordinate and complete complex tasks.

---

<img src="doc_en/screenshots/agent_web.png" alt="OpenSquad single-agent web workspace" width="900" />

<img src="doc_shared/screenshots/chat_group.png" alt="OpenSquad group chat" width="900" />

---

What is OpenSquad

OpenSquad enables multiple AI agents to collaborate like a real team. Each agent runs as an independent process with its own LLM connection, tool set, and memory. Agents communicate through group chat, coordinated by a PM agent, to tackle complex tasks that a single agent cannot handle alone.

What Problems It Solves

A single AI agent has clear limitations when dealing with complex projects:

• Limited context window — Cannot handle the full context of requirements, coding, and testing simultaneously
• Role confusion — One agent juggling multiple roles leads to oversight
• No parallelism — Serial execution results in low efficiency
• No review process — No independent QA role for quality assurance

OpenSquad solves these through multi-agent collaboration: PM handles task decomposition and coordination, Coder focuses on implementation, QA independently verifies — each with a clear responsibility.

Architecture (overview)

flowchart TB
    User["User / Web UI"] --> GW["Gateway :9555"]
    GW --> LA["Launcher :9600"]
    LA --> PM["PM Agent"]
    LA --> Dev["Coder Agent"]
    LA --> QA["QA Agent"]
    PM & Dev & QA --> IM["Group chat / IM"]
    PM & Dev & QA --> Plugins["Plugins / MCP / Skills"]
    Plugins --> Svc["Service plugins e.g. websearch :9001"]

Details: Architecture · Documentation hub

Key Features

• Collab Card driven — Predefined workflow templates (software dev, code review, research, etc.) with PM coordinating the team per card protocol
• Group chat communication — Agents collaborate via natural language group chat with @mentions, sleep/wake, and status queries
• Independent process architecture — Each agent runs independently, can be restarted and configured separately
• Long-term memory — Cross-session semantic memory system for agents to accumulate experience and knowledge
• Interruptible sleep — Agents can proactively sleep and wait for events, auto-waking on new messages
• Plugin system — 20 built-in plugins covering search, voice, version control, platform integrations, and more
• Skill system — Reusable task instructions defined via Markdown files
• MCP support — Dynamically connect external MCP servers to extend tool capabilities
• Multi-platform access — Web UI, Telegram, Feishu/Lark, QQ, and other interaction channels
• Local-first — Data and API keys stay on your machine, no third-party upload required

---

Quick Start (about 10 minutes)

1. Clone this repository.
2. Install with uv sync (or install.bat / install.sh).
3. Configure LLM: copy a model card template and set api_key in src/model_cards/ (see model cards guide).
4. Initialize workspace: uv run opensquad init (creates ~/.opensquad/workspace by default).
5. Start services: uv run opensquad start.
6. Open UI: http://127.0.0.1:5173 (or Gateway port from system_config).

Prerequisites

• Python 3.11+ (officially tested on 3.11 / 3.12 / 3.13)
• Node.js 18+ for frontend development; the Mods host needs Node.js 20.6+ (it loads mods through module.register, and transpiles their .ts / .tsx with a vendored sucrase — so no Node-version-dependent type stripping)
• A compatible LLM API (DeepSeek, GPT-4, Claude, Gemini, GLM, etc.)

---

Option 1: One-Click Script (Recommended, Beginner Friendly)

Windows

git clone https://github.com/opensquad-ai/opensquad.git && cd opensquad && install.bat

Linux / macOS

git clone https://github.com/opensquad-ai/opensquad.git && cd opensquad && bash install.sh

The script automatically: checks prerequisites → installs dependencies → initializes workspace → starts all services.

Note: After first start, add your LLM API key to a model card under src/model_cards/.

Option 2: uv (Recommended)

uv is a fast Python package manager. Recommended.

# Install uv (if not already)
pip install uv

# Clone the project
git clone https://github.com/opensquad-ai/opensquad.git
cd opensquad

# Install dependencies (uses uv.lock for reproducible builds)
uv sync

# Install frontend dependencies
cd src/opensquad/gateway/nexuschat-pro && npm install && cd ../../..

# Initialize and start
uv run opensquad init
uv run opensquad start

Option 3: pip

From PyPI — runtime, built web UI and the default resources:

pip install opensquad

opensquad init
opensquad start

Since 0.8.48 the wheel is a complete deployment. It ships the default model_cards/, plugins/, agents/, pymcp/, collab_cards/, role_cards/ and skills/ next to the opensquad package, so opensquad init seeds a runnable workspace and opensquad start finds every service. One gap remains: a fresh pip workspace has no system_config.json (the wheel carries no template), so ports stay on their defaults — gateway 9555, launcher 9600, registry 9720, frontend 5173 — until you save one from the Web UI's Settings.

From a checkout — full deployment, editable install:

git clone https://github.com/opensquad-ai/opensquad.git
cd opensquad

pip install -e .

# Install frontend dependencies
cd src/opensquad/gateway/nexuschat-pro && npm install && cd ../../..

# Initialize and start
opensquad init
opensquad start

Option 4: npm (Node.js users)

The npm package is a thin bootstrap: on first run it installs the matching Python opensquad CLI, then forwards every command to it.

npm install -g opensquad-ai

opensquad init
opensquad start

Requires Node.js 18+ (Mods host: 20.6+) and Python 3.11+. npx opensquad-ai works too, with no global install.

Option 5: Docker

git clone https://github.com/opensquad-ai/opensquad.git
cd opensquad

# Start (auto-builds image)
docker compose up -d

# View logs
docker compose logs -f

After start, visit http://localhost:9555. Data is persisted in Docker volumes.

Custom configuration:

# Edit config
cp src/system_config.example.json src/system_config.json
# Fill in your LLM API Key...

# Mount config and start
docker run -d \
  -p 9555:9555 -p 9600:9600 -p 9720:9720 \
  -v opensquad-data:/data \
  -v ./src/system_config.json:/app/src/system_config.json:ro \
  opensquad

---

Updating

Use the row that matches how you installed OpenSquad:

Installed via	Update with	Notes
Desktop app (installer)	In-app Check for updates, or opensquad update	Fully automatic: it downloads the installer, installs it silently and relaunches the app. Builds older than v0.8.43 must download the installer once by hand — the relaunch-on-update logic shipped in that version.
pip install opensquad	pip install --upgrade opensquad
npm install -g opensquad-ai	npm install -g opensquad-ai@latest	The wrapper re-installs the matching Python package when the versions differ.
git clone (uv sync / pip install -e .)	git pull, then re-run the same install command	Re-run npm install under src/opensquad/gateway/nexuschat-pro if the frontend changed; npm run build there to serve the UI statically instead of through Vite.
Docker	git pull && docker compose up -d --build	The image is built from the local Dockerfile, not pulled from a registry.

opensquad update only installs anything for the packaged desktop app. It cannot rewrite a pip / npm / source install, so on those it prints the command from the table and exits — without touching your environment or your git state.

---

Services

opensquad start launches all 4 services:

Service	Port	Description
Gateway Backend	9555	FastAPI backend (WebSocket + HTTP)
Plugin Registry	9720	Plugin store API
Frontend Dev	5173	Vite React frontend
Launcher	9600	Agent process manager

Open http://127.0.0.1:5173 in your browser to create and configure agents via the Web UI.

---

CLI Commands

Command	Description
opensquad init [--workspace <path>]	Initialize workspace (default: ~/.opensquad/workspace)
opensquad start [--port <port>]	Start all services
opensquad stop	Stop all OpenSquad services (frontend, gateway, launcher, adapters, agent processes)
opensquad status	Show agent and service status
opensquad plugin list	List installed plugins
opensquad plugin install <id>	Install a plugin from the store or Git URL
opensquad plugin uninstall <id>	Uninstall a plugin

Run without installing:

python -m opensquad.cli start

---

Configuration

Copy system_config.example.json to your workspace or src/system_config.json (see architecture-paths):

{
  "hosts": { "gateway": "127.0.0.1" },
  "ports": { "gateway": 9555, "launcher": 9600, "websearch": 9001 },
  "auth": { "node_secret": "your-secret-here" }
}

Never commit real system_config.json, auth.json, or model cards with API keys.

LLM API keys live in model cards (src/model_cards/*.json). Agents are created via the Web UI at runtime.

---

Documentation

Start here: Documentation hub → Getting started (EN)

Document	Description
Architecture	System design and module map
Collaboration	Multi-agent workflows
Plugin ecosystem	Built-in plugins vs Registry
Contributing	How to contribute
Releasing	Maintainer release checklist

---

Contributing

Issues and Pull Requests are welcome! Please read the Contributing Guide and Code of Conduct first.

---

License

MIT License — see LICENSE for details.

Powered by OpenSquad Core