# JiuwenSwarm: a multi-agent workbench you reach from chat apps, browser or terminal > JiuwenSwarm is a Python agent system from openJiuwen that splits complex work across a Leader and specialized teammates, with Skills that rewrite themselves after failures. Here is what the repository actually documents, and where it stays silent. **openJiuwen-ai/jiuwenswarm** — JiuwenSwarm is an intelligent AI Agent built on openJiuwen. It extends the powerful capabilities of large language models directly to your fingertips through various communication apps you use daily. - Repository: https://github.com/openJiuwen-ai/jiuwenswarm - Stars: 6,552 · Forks: 1,128 - Language: Python - License: Apache-2.0 - Published: 2026-08-04 · Updated: 2026-08-18 · Language: en - Canonical page: https://hysenlabs.com/projects/openjiuwen-ai-jiuwenswarm ## The problem JiuwenSwarm is aimed at Most agent tools assume one model doing one loop. JiuwenSwarm assumes the opposite: that a task is large enough to need a planner, several specialists, and a way for a human to step in halfway. The README frames it as an Agent system that makes multi-agent collaboration work, aimed at developers and teams automating complex tasks. The stated promise is end-to-end delivery from intent to result, with the user driving collaboration, Skill self-evolution and tool invocation through natural language. The target user is narrower than that sentence suggests. The install paths split into a one-click desktop build for Windows, macOS and HarmonyOS, and a pip or source install for Linux. If you only want a chat window over one model, the desktop build is the whole product for you. The Cluster mode, Swarmflow scripts and Skill Hub exist for people who already know they need several agents and want the orchestration handled rather than hand-rolled. ## Leader, teammates and the two execution modes The architecture visible in the README is a Leader plus Teammates. In Cluster mode, which the README marks as the default, a Leader decomposes a task and assembles teams; the specialist agents then negotiate dynamically. The README also states that Leader and Teammates can be deployed across processes and machines, which is what the Distributed Agent Swarm row in the capability table means. The second mechanism is Swarmflow. This is the deterministic layer: multi-stage workflows written as Python scripts, where the Leader hands off between stage agents. The README lists three features attached to it. HITL support comes in two forms, `human` and `human_session`. There is a team token budget. And the TUI exposes a `/swarmflows` run-tree view for monitoring. That combination is the interesting design choice: instead of letting the Leader improvise the whole path, you can pin the stages and only let the Leader decide who runs each one. Agent mode is the simpler branch. A single agent handles the task with planning and dynamic adjustment, which the README recommends for daily tasks, Q&A and code generation. The workbench itself has two spaces, Work and Code, switched from a selector in the top-left, and conversations pick their mode from a selector in the chat input area. In IM channels and the TUI, the `/mode` command does the same switch. ## Installing JiuwenSwarm and running a first task The README gives three install routes. Desktop is a one-click installer from the openjiuwen.com download page for Windows 10 or 11, macOS on Intel or Apple Silicon, and HarmonyOS PC. Linux has no desktop build, so the README points to the command line or source installs below it. The command line route is the shortest. The README shows four commands in sequence: install the package, run the initializer, start the service, then open the frontend. ```bash pip install jiuwenswarm jiuwenswarm-init jiuwenswarm-start ``` After `jiuwenswarm-start`, the README says to visit http://localhost:5173 for the frontend. The China mirror variant replaces the install line with `pip install jiuwenswarm -i https://pypi.tuna.tsinghua.edu.cn/simple`, which the README marks as recommended. The terminal interface is a separate package and needs its own terminal window after the service is running. The README is explicit about the ordering. ```bash pip install jiuwenswarm-tui jiuwenswarm-tui ``` If you prefer a checkout, the README's source path uses uv rather than pip. Note that the repository's Makefile routes Python invocations through `uv run python` and wraps the same workflow in `make install`, `make sync` and `make lock` targets. ```bash git clone https://github.com/openJiuwen-ai/jiuwenswarm.git cd jiuwenswarm uv venv uv pip install -e . ``` Before anything useful happens you must set a default model. The README calls this the one piece of configuration you cannot skip, and says the file `~/.jiuwenswarm/config/config.yaml` is created on your first `jiuwenswarm-start`. You can edit it directly or use More then Configuration in the web UI. Saving reloads the config without a restart, which is a genuinely convenient detail. ```yaml model_name: deepseek-v4-flash api_base: https://api.deepseek.com api_key: sk-your-api-key model_provider: OpenAI ``` That example is the README's DeepSeek configuration. The supported list includes Huawei Cloud MaaS, OpenAI, DeepSeek, DashScope, SiliconFlow, OpenRouter, other OpenAI-compatible APIs, and local model deployment. Once the model answers, the quickest real test is the README's Agent mode example, which asks for weather plus three book recommendations. For a Cluster mode test, the README's example is a research task on the new energy vehicle industry producing an analysis report. ## Where JiuwenSwarm is the wrong tool The dependency list is the first warning. `openjiuwen` is pinned to a git URL at a specific commit on gitcode.com, not to a released version on PyPI. That means your install depends on network access to gitcode.com and on that commit remaining reachable. If your build environment is air-gapped or your policy forbids VCS dependencies, the pip route does not fit, and the README does not document an offline or vendored alternative. The Python constraint is also tight: `requires-python = ">=3.11,<3.14"` in pyproject.toml. A team standardised on Python 3.9 or 3.14 has to change interpreters before anything else works. Second, the release history is beta-heavy. The three most recent releases are 0.2.6.beta1, 0.2.5 and 0.2.5.beta1, and the version in pyproject.toml on the develop branch reads 0.2.5.beta1. The last push to the repository was on 2026-08-26. Nothing here suggests abandonment, but the versioning pattern says interface churn is still happening. Third, the safety story is described in one table row, not in the install guide. The README claims that tools require approval before execution, file access goes through a whitelist, and sensitive operations are intercepted. Those are the right defaults for an agent that can touch your filesystem, but the README does not document how to configure the whitelist, what the interception rules are, or how to audit what was approved. If your threat model requires an auditable approval log, verify that before rollout rather than after. ## How it differs from a single-loop agent framework The obvious comparison is a general agent framework where you write the loop yourself and wire tools into it. In that model, multi-agent behaviour is something you build: you decide how to split a task, how sub-agents report back, and how state moves between them. JiuwenSwarm moves that decision into the runtime. The Leader decomposes and assembles; the framework handles the handoff. Swarmflow goes further and lets you fix the stage sequence in a Python script when you do not want the decomposition to be improvised. The second difference is where you talk to it. A framework typically gives you a library and a Python entry point. JiuwenSwarm ships a browser frontend on port 5173, a separate TUI package, and adapters for chat platforms: the dependency list includes `python-telegram-bot`, `discord.py`, `slack-bolt`, `dingtalk-stream` and `wecom-aibot-sdk`. That is a deliberate bet that the interface people want is the chat app they already have open, not a notebook cell. The third is the Skill lifecycle. Skill self-evolution is described as detecting error signals and user dissatisfaction, then optimizing Skill definitions. Skills are also shareable through the Swarm Skills Hub, where the README says you can search, install, remix and publish them. A framework gives you a prompt file you edit by hand; JiuwenSwarm gives you a mutable capability asset with a distribution channel attached. Whether automatic rewriting of a Skill is a feature or a risk depends on how much you trust the error signal, and the README does not describe the detection threshold. ## Licence, upgrades and what a bump costs The project is Apache-2.0, declared both in the repository's LICENSE file and in the `license` field of pyproject.toml, with the classifier "License :: OSI Approved :: Apache Software License". That is a permissive licence with an explicit patent grant and a requirement to preserve notices. The repository also carries an OPEN_SOURCE_SOFTWARE_NOTICE.md and a third_party directory, which is where bundled or vendored components are accounted for. If you redistribute JiuwenSwarm inside a product, read those two artifacts rather than assuming the top-level licence covers everything. This is a description of what the files say, not legal advice. Upgrade cost is dominated by two things. The first is the `openjiuwen` git pin: bumping JiuwenSwarm means potentially moving to a new upstream commit, and the Makefile exposes `update-openjiuwen` as a dedicated target, which tells you the maintainers expect that to be a routine operation rather than a rare one. There is also a `genai-semconv` target pair, `genai-semconv` and `check-genai-semconv`, that regenerates TypeScript constants in this repository and Python constants in a sibling agent-core checkout, with `AGENT_CORE_DIR` and `GENAI_SEMCONV_REVISION` as overridable variables. That is a two-repository workflow, and it is worth knowing about before you fork. The second is the dependency floor policy. Several entries in pyproject.toml carry inline CVE comments, for example `python-multipart>=0.0.31,<0.1` annotated with a MultipartParser DoS, `lxml>=6.1.0,<7` annotated with an XXE, and `pillow>=12.2.0,<13` annotated with a FITS gzip bomb. Those floors exist to stop a resolver from downgrading into a known vulnerability. Practically, it means you should not hand-relax them to resolve a conflict elsewhere in your tree. ## Conclusion Adopt JiuwenSwarm if you want a Leader-and-teammates agent runtime you can drive from a browser, a TUI or an IM channel, and you are comfortable pinning openjiuwen to a git revision. Do not adopt it if you need a stable, fully documented API surface or an air-gapped install with no PyPI access, because the README documents no offline path and the dependency list reaches out to gitcode.com. Before committing, verify that jiuwenswarm-init finishes on your Python version (the project requires >=3.11,<3.14) and that your model provider works against the OpenAI-compatible api_base you set in config.yaml. ## FAQ ### What is swarm AI and how does it work in JiuwenSwarm? In JiuwenSwarm, swarm AI means a Leader agent decomposes a complex task and assembles a team of specialized agents that negotiate dynamically. The README also states that Leader and Teammates can be deployed across processes and machines, and that Swarmflow can pin the stage sequence in a Python script when you do not want the decomposition improvised. ### Is JiuwenSwarm free? The repository is licensed under Apache-2.0, declared in both the LICENSE file and the license field of pyproject.toml. That covers the software itself; model usage through a provider such as DeepSeek, OpenAI or Huawei Cloud MaaS is a separate arrangement you configure in config.yaml. ### How do I install JiuwenSwarm on Linux? The README says Linux has no desktop build and points to the command line or source routes. The command line route is pip install jiuwenswarm, then jiuwenswarm-init, then jiuwenswarm-start, after which the frontend is at http://localhost:5173. The source route clones the repository and uses uv venv followed by uv pip install -e . ### Does JiuwenSwarm need a model configured before it works? Yes. The README calls the default model the one piece of configuration you cannot skip, and says the file ~/.jiuwenswarm/config/config.yaml is created on your first jiuwenswarm-start. Saving that file reloads the config without restarting the service. ### What is the difference between Agent mode and Cluster mode in JiuwenSwarm? Agent mode has a single agent handle the task with planning and dynamic adjustment, and the README recommends it for daily tasks, Q&A and code generation. Cluster mode is the default and uses a Leader to orchestrate multiple specialized agents for large tasks needing several roles. The /mode command switches between them in IM channels and the TUI. ## Sources - [Official README](https://github.com/openJiuwen-ai/jiuwenswarm#readme) - [Project repository](https://github.com/openJiuwen-ai/jiuwenswarm) - [Release notes](https://github.com/openJiuwen-ai/jiuwenswarm/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/openjiuwen-ai-jiuwenswarm