OpenSwarm: three exit codes, three names, and three instances solved

Exit code 2 means the gate did not run at all

The quick start is four lines, and the last two are the two modes of the gate:

npm install -g @intrect/openswarm
export OPENROUTER_API_KEY=…              # or use an authenticated codex/claude/local provider
openswarm review --path . --read-only    # review the current diff without mutation
openswarm review --max --fix --path .    # fix confirmed findings, re-review, then verify

review is designed to be a CI merge gate, and CI reads nothing except the exit code. The contract has three values.

Zero means the gate ran and did not reject, whether the verdict was approve or revise, or there was nothing to review at all. One means the gate ran and the verdict is reject, and with --fix it also covers the case where an area is left unresolved or deterministic verification did not pass. Two means the gate did not run: no verdict was produced, because of a provider usage limit, an adapter failure, or unparseable reviewer output. The instruction attached to two is blunt, never treat this as a pass.

Any non-zero value fails the check, and the split exists so a workflow can retry or alert differently when the gate could not run, for example when a quota window is exhausted. In that case stderr names the cause and, when it is known, the reset time.

The composite action wires the same contract into a job, with contents read, security-events write for the SARIF upload, a checkout at fetch depth 0 so the merge base exists to diff against, and Node 22.

The package, the repository and the action carry three different names

The npm package is @intrect/openswarm, published from this repository, which is Intrect-io/OpenSwarm.

The links do not match. The GitHub Discussions invitation points at github.com/unohee/OpenSwarm, and the composite action used in the CI example is referenced as unohee/OpenSwarm as well.

So a reader who wants to vote on the roadmap is sent to a different account, and a workflow that copies the action reference from the documentation would pull from that account rather than from the repository they cloned. Neither of those is necessarily wrong, since an organisation can move a project and leave its history behind, but the README never explains the relationship and the repository itself declares no homepage to arbitrate.

The install command has no such ambiguity, since npm install -g @intrect/openswarm names the package directly.

Three solved instances, and a rubric that has to be read

The verification claim is narrow and worth quoting accurately. The agentic harness is described as solving SWE-bench Lite instances graded by the official harness, and hybrid mode, where a frontier model diagnoses read-only and a lightweight model implements with a verification loop, resolved 3 out of 3 attempted instances that every single lightweight model had failed, at a fraction of frontier-only cost.

Three instances is three. No pass rate, no comparison table, and no instance list appears in the README; the numbers behind the claim live in benchmarks/RUBRIC.md, which is linked as the benchmark rubric and results.

There is a second claim in the same paragraph that is architectural rather than numeric: workers learn each repository over time, with task outcomes stored as per-repo knowledge and recalled into future prompts.

Release numbering has a gap worth noting for anyone pinning versions. The recent tags are v0.24.1 and v0.24.2 on 2026-09-20 and v0.24.4 on 2026-09-29, with no v0.24.3 among them, while the manifest already reads 0.24.4.

The dashboard refuses an unauthenticated bind, and the compose file publishes the port

The compose file carries one of the better-documented security decisions in this repository. The dashboard binds 127.0.0.1 inside the container unless a token is set, and an unauthenticated all-interfaces bind is refused by design. The comment spells out the consequence: without the token the published port answers nothing, while the daemon and the in-container healthcheck keep working. With it, reads and mutations from outside require an X-OpenSwarm-Token header, and /api/health is deliberately left open.

The variable is OPENSWARM_WEB_TOKEN, defaulted to empty. The published mapping is 3847 to 3847, so the port is reachable from outside the container either way.

Two other defaults are visible in the same file. The container timezone is fixed to Asia/Seoul, which will be wrong for most deployments. And the agents read a warehouse through a read-only mount while the operator web UI writes through a second mount of the same host directory, which is a deliberate separation of read and write paths to the same data.

The ci script lints, typechecks and builds, and never runs the tests

The manifest is worth reading for the gap in its own scripts. The ci entry is three commands: lint, typecheck and build. Linting uses oxlint over src/ and the dashboard's static JavaScript, typechecking runs tsc against a separate tsconfig.check.json, and the build is plain tsc with a postbuild step that sets the executable bit on dist/cli.js and copies web/static into dist/web-static, since without it the dashboard serves nothing.

The test suite exists and is not in that chain. It runs through vitest invoked with the node experimental VM modules flag, and there are separate entries for coverage, for watch mode, for a responsive dashboard check, and for a Playwright rendering performance measurement.

So the project's one aggregate CI command does not execute its own tests, and a contributor reading that script has no signal about the suite.

The lifecycle scripts are also blunt: predev and prestart run pkill against the dev and dist process patterns, and stop does the same, printing No process running when nothing matches.

Two stages on one libc because two native addons have to survive

The Dockerfile explains its own history in the header comment. Builder and runtime are both node:22-slim on glibc, so the native addons, named as better-sqlite3 and lancedb, are compiled once in the builder and copied into the runtime, leaving the runtime stage with no toolchain and no chance of drifting from what was built.

The comment records what went before: an Alpine builder on musl paired with a slim runtime on glibc forced a second, toolchain-less rebuild in the runtime stage, and that only worked while every native dependency happened to ship a prebuilt binary.

The runtime image installs git and gh because workers commit and open pull requests, and bubblewrap for the verification sandbox, which is described as failing closed under Docker's default seccomp profile. It runs the headless daemon with the dashboard on 3847 and bundles the openswarm CLI.

One thing is deliberately absent: the provider CLIs for claude, codex and cursor are not baked into the image, because the default adapter runs OpenSwarm's own tool loop against mounted OAuth state from ~/.openswarm and ~/.codex.

Three questions, two files written, and a refusal to overwrite

The wizard asks three things. The AI provider for worker and reviewer, where the options are a ChatGPT OAuth login that it calls the easiest start, an external codex CLI, OpenRouter, OpenAI OAuth, a local server through LM Studio or local with no account at all, and claude via the claude -p CLI as an opt-in fallback. The task backend, either a local SQLite issue store with no account or Linear with an OAuth login or API key followed by an arrow-key team to project picker. And an optional notification channel: none, discord, slack, telegram or webhook.

It then writes .env for secrets with mode 600, a validated config.yaml, and openswarm.json when a Linear project was mapped.

The guardrails are explicit. Re-running in a repository that already has config.yaml is refused unless --force is passed, and init refuses to overwrite a config.yaml that symlinks into the daemon's global config, which is the case that would silently break an existing install. For non-interactive use, openswarm init --yes writes a sample config only.

Editorial conclusion

OpenSwarm is worth taking seriously on two counts: it separates a failed verdict from an absent one, which most agent gates do not, and it refuses to expose its dashboard without a token. Before you wire it into a repository, check the provider story, because the sponsor adapter, the OAuth path and the local path have different cost and privacy implications, and treat the benchmark as a three-instance result rather than a general claim. Pin the image to a commit tag before running the daemon anywhere shared.

Frequently asked questions

Official sources

1. Intrect-io/OpenSwarm on GitHub
2. Issues
3. License: MIT
4. README
5. Releases