Intrect-io/OpenSwarm

OpenSwarm – AI‑powered CI/CD gate

What it is – OpenSwarm is a command‑line tool (and GitHub Action) that puts a large‑language‑model reviewer in front of your pull‑request or local diff. It can:

• Review code changes using OpenAI, OpenRouter, Claude, or locally‑hosted models.
• Fix confirmed issues in isolated sandboxes, then re‑review the result.
• Verify deterministically (run tests/type‑checks) before allowing a merge.
• Persist knowledge per repository so later runs get better prompts.
• Optionally hook into Linear for issue tracking, and send notifications to Discord/Slack/Telegram.

Why it matters – Traditional CI only runs static checks; OpenSwarm adds an agentic step that can understand the change, suggest and apply fixes, and only passes the gate when a deterministic verification succeeds. It aims to reduce manual code‑review cycles and catch bugs early, while keeping costs low by routing cheap models for implementation and frontier models for diagnosis.

---

Core concepts

Concept	Description
Provider	The LLM backend (Codex/GPT, OpenRouter, Claude, local Ollama/LM Studio, Atlas Cloud). The tool can auto‑detect auth or run a login wizard.
Task backend	Stores issue metadata in a local SQLite DB or in Linear (OAuth).
Sandbox	Linux sandbox (bubblewrap) or macOS sandbox isolates any code the model generates before it is applied.
Deterministic verification	Runs repository‑wide tests/type‑checks (Node, Python, Rust, Go, etc.) in a sandbox and compares against the merge‑base to ensure new failures are not introduced.
Daemon	Optional long‑running service that keeps repository memory, Linear integration, and notifications. Not required for the basic review gate.

---

Quick start (CLI)

# Install globally
npm install -g @intrect/openswarm

# Review current diff (read‑only, no changes)
openswarm review --path . --read-only

# Full auto‑fix flow: review → fix → re‑review → verify
openswarm review --max --fix --path .

• openswarm init runs an interactive wizard to create .env, config.yaml and optional openswarm.json (Linear mapping).
• openswarm doctor checks that providers, sandbox, and dependencies are ready.

---

Using in CI (GitHub Action)

steps:
  - uses: actions/checkout@v4
    with: { fetch-depth: 0 }
  - uses: actions/setup-node@v4
    with: { node-version: '22' }
  - id: review
    uses: unohee/OpenSwarm@main
    with:
      adapter: openrouter          # which provider to use
      model: deepseek/deepseek-v4-flash
    env:
      OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}

• The action returns decision and gate‑ran outputs and exits with 0 (pass) or 1 (reject). Exit code 2 signals the gate could not run (e.g., quota exhausted).

---

Main commands (summary)

Command	Purpose
openswarm (default)	TUI chat interface for ad‑hoc conversations with the model.
openswarm review …	Run the CI gate on a diff; --max audits the whole repo, --fix applies sandboxed fixes.
openswarm fix …	Run language‑specific CI checks (lint, test, etc.) and auto‑fix failures.
openswarm pr …	Interact with open pull requests – status, fix, review, create, watch until merge‑ready.
openswarm exec …	Execute a single task or a Linear issue pipeline, optionally awaiting human elevation.
openswarm check …	Scan the codebase, register entities, detect “bad‑code‑smell” patterns, annotate functions.
openswarm provider …	Switch or show the active LLM provider.
openswarm doctor	Diagnose environment, missing deps, provider auth, sandbox availability.

---

Sandbox & security notes

• Read‑only mode (--read-only) is the default; it disables any mutating tool in the model’s toolset.
• On Linux the tool uses bubblewrap; CI runners must install bubblewrap and enable unprivileged user namespaces (sysctl kernel.apparmor_restrict_unprivileged_userns=0).
• The reviewer runs on a temporary checkout, never on the runner’s working directory, preventing a malicious PR from overwriting the action’s own code.

---

Licensing & community

• License: MIT
• Sponsor: Atlas Cloud (provides the built‑in atlascloud adapter and API credits).
• Discussions: GitHub Discussions are used for roadmap voting and feature ideas.
• Benchmarks: Claims 3/3 success on SWE‑bench Lite hybrid mode, with a cost‑aware routing ladder (L0–L6).

---

When to consider OpenSwarm

• You already use LLMs for code assistance and want to automate the review/fix loop in CI.
• You need a deterministic gate that only passes when repository tests succeed after any auto‑fixes.
• You are comfortable configuring API keys for OpenAI/OpenRouter/Claude or running a local model server.
• You want optional Linear issue tracking and notification channels.

---

Limitations / things to watch

• Requires a working sandbox (bubblewrap) on Linux; CI images may need extra sysctl tweaks.
• Cost‑aware routing depends on the provider’s pricing; using frontier models for every run can become expensive.
• The daemon (for long‑term memory, Linear sync, notifications) is optional but adds operational complexity.
• The tool is written in TypeScript/Node; projects not using Node may still work but will need appropriate adapters for test discovery.

---

Bottom line – OpenSwarm is a genuine, open‑source AI‑augmented CI/CD gate that lets LLMs review, fix, and verify code changes automatically, with sandboxed execution and optional integration with Linear and notification services. It is suitable for teams looking to embed LLM‑driven automation into their pull‑request workflow while keeping a deterministic safety net.