HKUDS/AutoSwarm

AutoSwarm – Automating AI Agent Swarms

What it is

• An open‑source Python framework that lets you create, run, and evolve a whole AI‑powered organization (a “company”) to tackle complex, real‑world tasks.
• It combines a CLI and a web‑based Office UI (React + Phaser) so you can interact with the swarm either from a terminal or a visual “office” where each role appears as an animated avatar.

Core ideas

Phase	What happens
Self‑Built	Given a goal, AutoSwarm drafts an org chart, selects or hires AI “employees” (agents) for each role, and stores them for future reuse.
Self‑Run	The team works on a Kanban board. A state‑machine drives each work‑item through plan → execute → review → integrate → rework phases, handling dependencies, blockers, and escalation to a human when needed.
Self‑Grown	After a run, outcomes are attributed to the responsible roles, lessons are distilled into private experience profiles, and reusable playbooks are generated for the next project.

Key features

• Company mode – run a multi‑role swarm with explicit reporting lines; roles can use different LLM back‑ends (Claude, Codex, OpenAI, etc.).
• Adaptive team creation – a recruiter agent can design the org chart and hire from a talent pool automatically.
• Kanban‑driven orchestration – visual board shows each item’s column, owner, and readiness; parallel work is automatically scheduled.
• Playbook learning – per‑role experience is persisted and shared, so the swarm gets smarter over time.
• JiuwenSwarm integration – plug in the JiuwenSwarm single‑agent or team as an opaque component.
• Two interfaces – autoswarm CLI for scripting/CI and an Office UI (http://localhost:8765) for interactive monitoring.
• Extensible plugins – external agents (e.g., Codex, Cursor) can be swapped per role; the system reports missing capabilities clearly.

Typical workflow

1. Setup – install with uv, run autoswarm init to create config, memory, and project folders.
2. Start UI – autoswarm ui (or opc ui) opens the Office UI.
3. Create a chat – pick Company mode, choose a pre‑built organization (e.g., Corporate) or let the system auto‑team.
4. Define the goal – the recruiter drafts roles, hires agents, and you approve the plan.
5. Run – the swarm executes tasks, you watch progress on the Kanban or Office view, intervene on blockers if needed.
6. Learn – after completion, AutoSwarm updates role experience and generates playbooks for future runs.

Installation (quick)

# Install uv (recommended)
brew install uv   # macOS
# or curl https://astral.sh/uv/install.sh | sh  # Linux/Windows

# Clone and set up the repo
git clone https://github.com/HKUDS/AutoSwarm.git
cd AutoSwarm
uv python install 3.12   # any >=3.10 works
uv venv --python 3.12
source .venv/bin/activate   # or .venv\Scripts\activate on Windows
uv pip install -e .
uv run autoswarm init
uv run autoswarm ui   # opens the UI at http://localhost:8765

(For headless use, replace autoswarm ui with autoswarm chat or autoswarm exec.)

Who might use it

• Product teams that want an AI “assistant crew” to prototype features, write code, or generate content.
• Researchers building multi‑agent simulations or evaluating LLM‑driven workflows.
• Consultants automating repetitive business processes (e.g., market research, investment memos) with a self‑organizing AI staff.
• Developers who need a programmable, reproducible environment for complex, multi‑step AI tasks.

Roadmap highlights

• More resilient company sessions (July 2026).
• JiuwenSwarm 0.2.4b4 compatibility (Sept 2026).
• UI performance improvements and smoother live updates.
• Persistent approvals and smarter automated decision flows.

License – MIT (see LICENSE).

---

All details are taken directly from the repository’s README; no external assumptions have been added.