Intrect-io/OpenSwarm

OpenSwarm – AI 기반 CI/CD 게이트

개요 – OpenSwarm은 풀 리퀘스트나 로컬 diff 앞에 대규모 언어 모델 검토자를 배치하는 명령줄 도구(및 GitHub Action)입니다. 다음과 같은 기능을 제공합니다:

• 검토: OpenAI, OpenRouter, Claude 또는 로컬 호스팅 모델을 사용하여 코드 변경 사항을 검토합니다.
• 수정: 격리된 샌드박스에서 확인된 문제를 수정하고 결과를 재검토합니다.
• 검증: 병합을 허용하기 전에 결정론적 검증(테스트/타입 체크 실행)을 수행합니다.
• 지식 유지: 리포지토리별로 지식을 유지하여 이후 실행 시 더 나은 프롬프트를 얻을 수 있습니다.
• 선택적으로 Linear와 연동하여 이슈를 추적하고 Discord/Slack/Telegram으로 알림을 보냅니다.

중요성 – 기존 CI는 정적 검사만 수행하지만, OpenSwarm은 변경 사항을 이해하고 수정 사항을 제안 및 적용하며 결정론적 검증이 성공할 때만 게이트를 통과시키는 에이전트 단계를 추가합니다. 수동 코드 검토 주기를 줄이고 버그를 조기에 발견하는 것을 목표로 하며, 구현에는 저렴한 모델을, 진단에는 최첨단 모델을 라우팅하여 비용을 낮게 유지합니다.

---

핵심 개념

개념	설명
Provider	LLM 백엔드(Codex/GPT, OpenRouter, Claude, 로컬 Ollama/LM Studio, Atlas Cloud). 도구가 인증을 자동 감지하거나 로그인 마법사를 실행할 수 있습니다.
Task backend	이슈 메타데이터를 로컬 SQLite DB 또는 Linear(OAuth)에 저장합니다.
Sandbox	Linux 샌드박스(bubblewrap) 또는 macOS 샌드박스가 모델이 생성한 코드를 적용하기 전에 격리합니다.
Deterministic verification	샌드박스 내에서 리포지토리 전체 테스트/타입 체크(Node, Python, Rust, Go 등)를 실행하고 병합 기준과 비교하여 새로운 오류가 도입되지 않았는지 확인합니다.
Daemon	리포지토리 메모리, Linear 통합 및 알림을 유지하는 선택적 상주 서비스. 기본 검토 게이트에는 필요하지 않습니다.

---

빠른 시작 (CLI)

# 전역 설치
npm install -g @intrect/openswarm

# 현재 diff 검토 (읽기 전용, 변경 없음)
openswarm review --path . --read-only

# 완전 자동 수정 흐름: 검토 → 수정 → 재검토 → 검증
openswarm review --max --fix --path .

• openswarm init은 .env, config.yaml 및 선택적 openswarm.json(Linear 매핑)을 생성하는 대화형 마법사를 실행합니다.
• openswarm doctor는 공급자, 샌드박스 및 종속성이 준비되었는지 확인합니다.

---

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          # 사용할 공급자
      model: deepseek/deepseek-v4-flash
    env:
      OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}

• 이 액션은 decision 및 gate-ran 출력을 반환하며 0(통과) 또는 1(거부)로 종료됩니다. 종료 코드 2는 게이트를 실행할 수 없음을 나타냅니다(예: 할당량 초과).

---

주요 명령어 (요약)

명령어	목적
openswarm (기본값)	모델과의 임시 대화를 위한 TUI 채팅 인터페이스.
openswarm review …	diff에서 CI 게이트 실행; --max는 전체 리포지토리 감사, --fix는 샌드박스 수정 적용.
openswarm fix …	언어별 CI 검사(lint, test 등)를 실행하고 실패를 자동 수정.
openswarm pr …	열린 풀 리퀘스트와 상호작용 – 상태, 수정, 검토, 생성, 병합 준비 완료까지 감시.
openswarm exec …	단일 작업 또는 Linear 이슈 파이프라인 실행(선택적으로 사람의 승인 대기).
openswarm check …	코드베이스 스캔, 엔티티 등록, "bad-code-smell" 패턴 감지, 함수 주석 처리.
openswarm provider …	활성 LLM 공급자 전환 또는 표시.
openswarm doctor	환경, 누락된 종속성, 공급자 인증, 샌드박스 가용성 진단.

---

샌드박스 및 보안 참고 사항

• 읽기 전용 모드(--read-only)가 기본값이며, 모델 도구 세트의 모든 변경 도구를 비활성화합니다.
• Linux에서 이 도구는 bubblewrap을 사용합니다. CI 러너는 bubblewrap을 설치하고 비특권 사용자 네임스페이스를 활성화해야 합니다(sysctl kernel.apparmor_restrict_unprivileged_userns=0).
• 검토자는 임시 체크아웃에서 실행되며 러너의 작업 디렉토리에서 실행되지 않으므로 악의적인 PR이 액션 자체의 코드를 덮어쓰는 것을 방지합니다.

---

라이선스 및 커뮤니티

• 라이선스: MIT
• 스폰서: Atlas Cloud(내장 atlascloud 어댑터 및 API 크레딧 제공).
• 토론: GitHub Discussions는 로드맵 투표 및 기능 아이디어에 사용됩니다.
• 벤치마크: SWE-bench Lite 하이브리드 모드에서 3/3 성공을 주장하며, 비용 인식 라우팅 사다리(L0–L6)를 갖추고 있습니다.

---

OpenSwarm을 고려해야 할 때

• 이미 코드 지원에 LLM을 사용하고 있으며 CI에서 검토/수정 루프를 자동화하려는 경우.
• 자동 수정 후 리포지토리 테스트가 성공할 때만 통과하는 결정론적 게이트가 필요한 경우.
• OpenAI/OpenRouter/Claude의 API 키를 구성하거나 로컬 모델 서버를 실행하는 데 익숙한 경우.
• 선택적 Linear 이슈 추적 및 알림 채널이 필요한 경우.

---

제한 사항 / 주의 사항

• Linux에서 작동하는 샌드박스(bubblewrap)가 필요합니다. CI 이미지에 추가적인 sysctl 조정이 필요할 수 있습니다.
• 비용 인식 라우팅은 공급자의 가격 책정에 따라 다릅니다. 모든 실행에 최첨단 모델을 사용하면 비용이 많이 들 수 있습니다.
• 데몬(장기 메모리, Linear 동기화, 알림용)은 선택 사항이지만 운영 복잡성이 증가합니다.
• 이 도구는 TypeScript/Node로 작성되었습니다. Node를 사용하지 않는 프로젝트도 작동할 수 있지만 테스트 검색을 위한 적절한 어댑터가 필요합니다.

---

결론 – OpenSwarm은 LLM이 코드 변경 사항을 자동으로 검토, 수정 및 검증할 수 있도록 하는 진정한 오픈소스 AI 강화 CI/CD 게이트입니다. 샌드박스 실행 환경을 갖추고 있으며 Linear 및 알림 서비스와 선택적으로 통합할 수 있습니다. 풀 리퀘스트 워크플로우에 LLM 기반 자동화를 도입하면서 결정론적 안전망을 유지하려는 팀에게 적합합니다.