ruflo(루플로) 입문 가이드 — Claude Code 멀티 에이전트 오케스트레이션 시작하기

이번 포스팅에서는 ruflo(루플로)를 처음 접하는 사람을 위해 설치부터 필수 설정, 첫 실행까지 정리하고자 한다. ruflo는 Claude Code와 Codex 위에 얹어 여러 AI 에이전트를 동시에 조율하는 오케스트레이션 도구다. 혼자 돌던 Claude Code 한 대를, 역할이 나뉜 여러 에이전트가 병렬로 협업하는 팀으로 바꿔 준다. 이름이 낯설 수 있는데, 원래 claude-flow라는 이름으로 유명하던 프로젝트가 상표 문제로 ruflo로 바뀐 것이다. 여기서는 어려운 고급 기능보다, 처음 깔고 돌려 보는 데 꼭 필요한 것만 짚는다. 모든 명령과 수치는 실제 ruflo v3.51.1을 돌려 확인한 값이다.

ruflo가 뭐길래 — Claude Code 위의 멀티 에이전트 오케스트레이션

ruflo는 Claude Code와 Codex를 감싸는 “에이전트 메타 하네스(meta-harness)”, 즉 여러 AI 에이전트를 조율하는 실행 계층이다. Claude Code 한 대만 쓰면 한 번에 한 가지 일만 시키지만, ruflo를 올리면 코더·리뷰어·테스터처럼 역할이 나뉜 에이전트들이 스웜(swarm)을 이뤄 병렬로 움직인다. 공식 저장소는 github.com/ruvnet/ruflo이고, GitHub 스타 수만 개를 모은 인기 프로젝트다.

ruflo가 더해 주는 건 크게 네 가지로 볼 수 있다. 역할별 전문 에이전트(init --help 기준 기본 약 24개, --all-agents로 전체 약 89개), 이들을 묶는 스웜 조율, 세션을 넘어 사실을 기억하는 self-learning 메모리, 그리고 여러 머신을 잇는 federation이다. 원래 claude-flow였던 만큼 npm 패키지는 ruflo와 claude-flow 두 이름이 모두 올라와 있고, 둘 다 같은 최신 버전(현재 v3.51.1)을 가리킨다. CLI 명령어도 ruflo를 쓴다.

Claude Code 자체를 더 깊이 다루는 법이 궁금하다면 Claude Code 실전 활용법 글을, AI 에이전트를 여러 개 병렬로 굴리는 다른 접근이 궁금하다면 Orca로 AI 코딩 에이전트 병렬 실행하기를 함께 보면 ruflo의 위치가 더 또렷해진다.

시작 전 준비물 — Node 20, Claude Code, 그리고 인증

ruflo를 깔기 전에 세 가지가 필요하다. Node.js 20 이상, 설치·로그인까지 끝난 Claude Code, 그리고 git 저장소(권장)다. 특히 Node 버전이 중요한데, 여러 블로그가 “Node 18 이상”이라고 적어 두었지만 실제 패키지가 요구하는 건 Node 20 이상이다. npm 패키지 페이지의 engines 필드가 node >=20.0.0으로 못 박혀 있고, 공식 Wiki도 “Node.js 20+”를 명시한다. 18로 돌리면 설치 단계에서 막힌다.

가장 자주 하는 오해가 “API 키를 따로 발급해야 하나?”인데, 그럴 필요가 없다. ruflo는 Claude Code를 통해 모델을 호출하므로 인증을 Claude Code에 위임한다. 실제로 뒤에서 볼 ruflo doctor 출력에도 API Keys: Claude Code (managed internally)라고 찍힌다. 즉 Claude Code에 이미 로그인돼 있다면 ruflo용 키를 또 만들 일은 없다. 정리하면 준비물은 아래와 같다.

표의 네 가지 중 Node 20과 Claude Code 로그인은 사실상 필수이고, git 저장소는 없어도 돌아가지만 ruflo가 변경 위험도 분석 같은 기능에서 git을 활용하므로 프로젝트를 git으로 관리하는 편이 낫다.

설치는 세 갈래 — npx, 전역, 플러그인

ruflo 설치는 크게 세 방법이 있고, 처음이라면 설치 없이 바로 쓰는 npx가 가장 가볍다. 아무것도 전역에 깔지 않고 최신 버전을 내려받아 실행하므로, 맛만 보고 지우기도 쉽다. 세 방법은 다음과 같다.

# 1) npx — 설치 없이 바로 실행 (처음 추천)
npx ruflo@latest init wizard

# 2) 전역 설치 — 자주 쓸 거라면
npm install -g ruflo@latest

# 3) Claude Code 플러그인으로 등록 (Claude Code 안에서 실행)
/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-core@ruflo

# 1) npx — 설치 없이 바로 실행 (처음 추천)
npx ruflo@latest init wizard

# 2) 전역 설치 — 자주 쓸 거라면
npm install -g ruflo@latest

# 3) Claude Code 플러그인으로 등록 (Claude Code 안에서 실행)
/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-core@ruflo

세 방법은 목적이 다르다. npx ruflo@latest ...는 전역 설치 없이 매번 최신 버전을 받아 실행하는 방식이라 처음 써 보기에 좋다. npm install -g ruflo@latest는 ruflo 명령을 전역에 깔아 두는 방식으로, 매번 내려받는 시간을 아끼고 싶을 때 쓴다. 세 번째는 Claude Code 안에서 마켓플레이스를 통해 플러그인으로 등록하는 방식인데, 마켓플레이스(ruvnet/ruflo)를 추가한 뒤 ruflo-core@ruflo를 설치하고 /plugin list에 ruflo-core가 보이면 성공이다(공식 설치 문서). 상황별로 정리하면 다음과 같다.

한 가지 짚어 둘 게 있다. 이 글의 명령은 모두 npx ruflo@latest <명령> 형태로 적었는데, 이건 전역 설치 없이 매번 최신 버전을 받아 실행하는 방식이라 입문자가 처음 써 보기에 좋다. 하지만 전용 CLI 명령이 따로 있다. npm install -g ruflo@latest로 한 번 전역 설치해 두면 이후로는 npx ruflo@latest를 뗀 짧은 ruflo <명령>을 그대로 쓸 수 있다. 예를 들어 npx ruflo@latest doctor는 전역 설치 후엔 그냥 ruflo doctor다. 그러니 몇 번 맛만 볼 생각이면 npx로, 계속 쓸 생각이면 전역 설치 후 짧은 ruflo 명령으로 가는 편이 편하다. 아래 예시들은 npx ruflo@latest로 적었지만, 전역 설치했다면 전부 ruflo로 줄여 읽으면 된다.

MCP 서버로 붙이고 싶다면 Claude Code에 한 줄로 등록할 수도 있다.

claude mcp add ruflo -- npx ruflo@latest mcp start

claude mcp add ruflo -- npx ruflo@latest mcp start

이 명령은 ruflo를 MCP 서버로 Claude Code에 연결해, 스웜·메모리 같은 기능을 MCP 도구로 노출한다. MCP가 생소하다면 MCP 실전 가이드를 먼저 읽고 오면 이 한 줄이 무슨 일을 하는지 바로 이해된다. 처음에는 굳이 MCP까지 붙이지 않고 npx로 시작해도 충분하다.

설치가 제대로 됐는지 — ruflo doctor로 환경 점검

설치 후 가장 먼저 할 일은 ruflo doctor다. 이 명령은 아무것도 바꾸지 않고 환경만 진단해, Node 버전·Claude Code 감지·API 키 상태·초기화 여부를 한 번에 보여 준다. 초보자가 “내 환경이 ruflo를 돌릴 준비가 됐나”를 확인하는 가장 빠른 방법이다.

npx ruflo@latest doctor

npx ruflo@latest doctor

실행하면 항목별로 ✓(정상)·⚠(경고)가 줄줄이 찍힌다. 그중 눈여겨볼 건 Node.js Version: v20.18.0 (>= 20 required)로 Node 요건을 확인해 주고, Claude Code CLI: v2.1.289로 Claude Code를 제대로 찾았는지, API Keys: Claude Code (managed internally)로 인증이 Claude Code에 위임돼 있음을 알려 준다. 아직 init을 안 했다면 Daemon Status: Not running, Memory Database Presence: Not initialized, Config File: No config file (using defaults) 같은 경고가 뜨는데, 이건 오류가 아니라 “아직 초기화 전”이라는 정상 신호다. 마지막 줄의 Summary: 17 passed, 15 warnings처럼 경고가 좀 있어도 설치 직후라면 괜찮다. 경고를 고치는 제안 명령이 궁금하면 --fix를 붙여 확인만 할 수 있다(자동 적용은 하지 않는다).

첫 설정 — ruflo init이 만드는 것들

ruflo를 실제로 쓰려면 프로젝트 폴더에서 init으로 초기화해야 한다. init은 .claude/, .claude-flow/ 디렉터리와 CLAUDE.md 파일을 만들어, 에이전트 정의·설정·헬퍼 스크립트를 깔아 둔다. 가장 쉬운 길은 대화형 마법사다.

# 대화형 마법사로 초기화 (질문에 답하며 설정)
npx ruflo@latest init wizard

# 또는 기본값으로 바로 초기화
npx ruflo@latest init

# 대화형 마법사로 초기화 (질문에 답하며 설정)
npx ruflo@latest init wizard

# 또는 기본값으로 바로 초기화
npx ruflo@latest init

init wizard는 질문에 답하며 구성을 잡아 주는 대화형 설정이라 처음에 추천된다. 답하기 번거롭다면 npx ruflo@latest init으로 기본 구성을 바로 깔 수도 있다. init에는 상황별 옵션이 여럿 있는데, 초보자가 알아 둘 만한 것만 추리면 다음과 같다.

표에서 보듯 처음에는 --minimal로 가볍게 시작했다가, 익숙해지면 --full이나 --all-agents로 범위를 넓히는 흐름이 무난하다. 초기화가 끝나면 ruflo init check로 제대로 깔렸는지 다시 확인할 수 있다. 참고로 init은 ~/.claude/CLAUDE.md에 “Ruflo Integration” 안내 블록도 한 번 추가하는데, 이게 싫다면 --no-global로 건너뛸 수 있다.

스웜과 데몬 — 먼저 개념부터

본격적으로 명령을 치기 전에 두 단어만 짚고 가자. 스웜(swarm)과 데몬(daemon)이다. 스웜은 역할이 나뉜 여러 에이전트가 하나의 목표를 향해 협업하는 팀을 뜻하고, 데몬은 그 에이전트들이 실제로 돌아갈 백그라운드 워커 프로세스다. ruflo를 쓴다는 건 결국 데몬을 띄워 두고 스웜에게 목표를 주는 일이다.

스웜을 조금 더 풀어 보면, Claude Code 한 대에 일을 몰아주는 대신 coder·tester·reviewer처럼 역할을 나눈 에이전트들에게 한 작업을 분담시키는 구조다. 이때 에이전트들을 어떤 모양으로 묶느냐가 토폴로지(topology)인데, swarm init의 --topology hierarchical은 지휘자 아래 작업자를 두는 계층형이고, mesh는 에이전트들을 서로 대등하게 연결하는 방식이다. 묶인 에이전트들은 공유 메모리로 서로의 결과를 주고받으며 협업한다. 혼자 도는 에이전트 여럿(orca·cmux 방식)과 달리, 스웜은 한 작업을 팀으로 나눠 푼다는 점이 다르다.

데몬은 왜 띄우는가. 에이전트는 한 번 명령하고 끝나는 게 아니라 백그라운드에서 계속 돌며 작업을 이어 간다. 데몬(daemon start)은 바로 이 백그라운드 워커를 호스팅하는 상주 프로세스다. 데몬이 떠 있어야 스웜이 터미널 명령 하나에 묶이지 않고 여러 작업을 비동기로 처리할 수 있다. 앞서 ruflo doctor에서 본 Daemon Status: Not running은 아직 이 워커가 꺼져 있다는 뜻이고, daemon start로 켜면 스웜이 돌아갈 무대가 준비된다.

첫 에이전트 띄우기 — daemon, swarm, agent

초기화를 마쳤다면 이제 백그라운드 데몬을 켜고 스웜을 하나 띄워 본다. 순서는 데몬 시작 → 스웜 초기화 → 에이전트 생성이다. 공식 Quick Start가 안내하는 첫 실행 흐름은 다음과 같다.

# 1) 백그라운드 워커 데몬 시작
npx ruflo@latest daemon start

# 2) 스웜 초기화 — 계층형 토폴로지, 최대 8개 에이전트
npx ruflo@latest swarm init --topology hierarchical --max-agents 8 --strategy specialized

# 3) 코더 에이전트 하나 생성
npx ruflo@latest agent spawn -t coder --name my-coder

# 1) 백그라운드 워커 데몬 시작
npx ruflo@latest daemon start

# 2) 스웜 초기화 — 계층형 토폴로지, 최대 8개 에이전트
npx ruflo@latest swarm init --topology hierarchical --max-agents 8 --strategy specialized

# 3) 코더 에이전트 하나 생성
npx ruflo@latest agent spawn -t coder --name my-coder

daemon start는 에이전트들이 돌아갈 백그라운드 워커를 띄운다. swarm init은 에이전트들을 묶는 조율 단위(스웜)를 만드는데, --topology hierarchical은 계층형 구조를, --max-agents 8은 최대 8개까지, --strategy specialized는 역할 특화 전략을 뜻한다. 마지막 agent spawn -t coder --name my-coder는 coder 타입 에이전트를 my-coder라는 이름으로 하나 띄우는 명령이다(Quick Start). 기억을 저장하고 싶다면 memory store 명령으로 키·값을 네임스페이스에 적어 둘 수도 있다.

# 재사용할 사실을 메모리에 저장
npx ruflo@latest memory store --key "auth-pattern" --value "JWT with refresh tokens" --namespace patterns

# 재사용할 사실을 메모리에 저장
npx ruflo@latest memory store --key "auth-pattern" --value "JWT with refresh tokens" --namespace patterns

이렇게 저장한 메모리는 세션을 넘어 유지되어, 다음 작업에서 에이전트가 다시 꺼내 쓴다. 처음에는 스웜 하나에 에이전트 한둘만 올려 두고, 동작을 눈으로 확인한 뒤 수를 늘려도 늦지 않다.

실전 예시 — 스웜에게 실제 작업 시키기

ruflo를 실제로 쓰는 핵심은 스웜에 목표(objective)를 주고 실행하는 것이다. 앞 절에서 daemon start와 swarm init으로 팀을 만들었다면, 이제 swarm start에 -o로 할 일을 적어 주면 ruflo가 그 목표를 하위 작업으로 쪼개 역할 에이전트에게 나눠 맡긴다. 예를 들어 “할 일(todo) REST API 만들기”를 시킨다면 이렇게 한다.

# 앞서 만든 스웜에 목표(-o)를 주고 실행, 전략(-s)은 개발용
npx ruflo@latest swarm start \
  -o "할 일 REST API 만들기: todo 생성·조회·수정·삭제 엔드포인트와 간단한 테스트" \
  -s development

# 앞서 만든 스웜에 목표(-o)를 주고 실행, 전략(-s)은 개발용
npx ruflo@latest swarm start \
  -o "할 일 REST API 만들기: todo 생성·조회·수정·삭제 엔드포인트와 간단한 테스트" \
  -s development

-o(--objective)가 스웜이 수행할 목표이며 필수값이고, -s development는 개발용 실행 전략이다. 이 명령을 내리면 ruflo가 목표를 하위 작업으로 분해해 coder·tester 같은 역할 에이전트에게 나눠 맡기고, Claude Code를 통해 코드를 생성·검토한다. --parallel(기본 켜짐)로 가능한 작업은 병렬로 처리하고, --monitor(기본 켜짐)로 진행 상황을 실시간으로 보여 준다. 진행 상태는 언제든 확인하고 필요하면 멈출 수 있다.

npx ruflo@latest swarm status   # 어떤 에이전트가 무엇을 하는지
npx ruflo@latest swarm stop     # 실행 중지

npx ruflo@latest swarm status   # 어떤 에이전트가 무엇을 하는지
npx ruflo@latest swarm stop     # 실행 중지

더 크거나 에이전트 간 합의가 필요한 작업은 hive-mind가 맞다. hive-mind는 Queen 에이전트가 작업을 지휘하는 방식으로, 목표를 들고 Claude Code를 바로 띄우거나(spawn --claude -o), 작업을 큐에 넣고 유휴 워커가 처리하게(task -d → work) 할 수 있다.

# 목표를 들고 Claude Code를 띄워 수행
npx ruflo@latest hive-mind spawn --claude -o "할 일 API에 사용자 인증 추가"

# 또는 작업을 큐에 등록 → 유휴 워커가 처리 → 상태 확인
npx ruflo@latest hive-mind task -d "할 일 API에 사용자 인증 추가"
npx ruflo@latest hive-mind work
npx ruflo@latest hive-mind status

# 목표를 들고 Claude Code를 띄워 수행
npx ruflo@latest hive-mind spawn --claude -o "할 일 API에 사용자 인증 추가"

# 또는 작업을 큐에 등록 → 유휴 워커가 처리 → 상태 확인
npx ruflo@latest hive-mind task -d "할 일 API에 사용자 인증 추가"
npx ruflo@latest hive-mind work
npx ruflo@latest hive-mind status

정리하면, 가벼운 작업은 swarm start -o "목표"로 바로 시키고, 지휘·합의가 필요한 큰 작업은 hive-mind로 간다. 둘 다 결국 Claude Code를 통해 실제 코드를 만들어 내므로, 목표 문장을 구체적으로 적을수록(무엇을·어디에·어떤 제약으로) 결과가 좋아진다. 실행되는 모습을 눈으로 보고 싶으면 다음 절의 /ruflo 콘솔을 함께 띄워 두면 된다.

Claude Code 안에서 — /ruflo 콘솔로 한눈에 보기

ruflo의 메인 화면은 웹 대시보드가 아니라 Claude Code 안에서 뜨는 TUI 콘솔이다. Claude Code에서 /ruflo를 입력하면 스웜·메모리·federation·비용을 한 화면에서 보여 주는 콘솔(“cockpit”)이 열린다. 터미널 기반 도구답게, 별도 브라우저 없이 Claude Code 안에서 모든 걸 조종하는 구조다.

콘솔에서는 지금 돌고 있는 스웜과 에이전트 상태, 저장된 메모리, 머신 간 federation 연결, 그리고 토큰 비용 추적을 함께 확인할 수 있다(공식 README). 콘솔은 사람이 직접 조작할 수도 있고, 권한 설정에 따라 Claude가 대신 조종하게 둘 수도 있다. 다만 이 콘솔은 ruflo 초기화와 Claude Code 로그인이 끝난 상태라야 열리므로, 앞의 init과 doctor를 먼저 통과시키는 게 순서다.

Claude Code 세션 안에서 바로 쓰기 — 슬래시 명령과 MCP

ruflo는 터미널 CLI로만 쓰는 게 아니라 Claude Code 세션 안에서도 바로 쓸 수 있다. 사실 ruflo init은 CLI 설정만 깔지 않는다. Claude Code 통합을 함께 설치하는데, 실제로 init을 돌려 보면 .claude/ 아래에 슬래시 명령 16개·에이전트 17개·skills 30개·hooks 7종이 깔리고, ruflo를 MCP 서버로 등록하는 .mcp.json과 스웜 가이드가 담긴 CLAUDE.md가 생긴다. init 한 번이면 터미널과 Claude Code 양쪽에서 쓸 준비가 끝나는 셈이다.

Claude Code 안에서 쓰는 길은 세 가지다. 첫째는 슬래시 명령이다. /를 치면 ruflo가 추가한 명령이 뜨는데, claude-flow-swarm·claude-flow-memory 같은 상위 명령과 swarm·hive-mind·memory 범주의 명령들(예: swarm-init, hive-mind-spawn, hive-mind-status)이 들어 있다. 둘째는 앞 절에서 본 /ruflo 콘솔이다. 셋째는 그냥 평소처럼 쓰는 것이다. init이 MCP 서버(.mcp.json)와 hooks를 켜 두기 때문에, Claude Code에서 자연어로 작업을 지시하면 hooks가 알아서 작업을 적절한 에이전트에게 라우팅하고 결과에서 패턴을 학습한다. 공식 안내도 “init 후에는 Claude Code를 평소처럼 쓰면 hooks가 자동으로 작업을 라우팅하고 에이전트를 띄운다”고 설명한다.

여기서 한 가지 주의할 점이 있다. 플러그인만 가볍게 설치하는 Lite 경로(/plugin install ruflo-core@ruflo)는 슬래시 명령과 에이전트 정의는 깔아 주지만 MCP 서버는 포함하지 않는다. 그래서 Claude가 메모리·스웜 도구를 직접 호출하게 하려면, init이 만든 .mcp.json을 쓰거나 아래처럼 MCP 서버를 따로 등록해야 한다.

claude mcp add ruflo -- npx ruflo@latest mcp start

claude mcp add ruflo -- npx ruflo@latest mcp start

이 명령은 ruflo를 MCP 서버로 Claude Code에 붙여, 스웜·메모리 같은 기능을 Claude가 직접 호출할 수 있는 도구로 노출한다. 참고로 ruflo doctor는 이렇게 노출되는 MCP 도구가 수백 개(실행 시점 기준 약 358개)에 달한다고 보고하는데, 그만큼 Claude가 자연어만으로 스웜을 다룰 여지가 넓다는 뜻이다. 요약하면, 슬래시 명령만 가볍게 쓸 거면 플러그인으로 충분하고, Claude가 스웜·메모리까지 자동으로 다루게 하려면 MCP 서버가 필요하다. MCP 자체가 생소하다면 MCP 실전 가이드를 먼저 보면 이 연결이 무슨 일을 하는지 또렷해진다.

명령 지도 — 초보자가 알아 둘 핵심 명령

ruflo 입문자가 먼저 익힐 핵심 명령은 doctor·init·status·swarm·agent·memory·daemon·mcp 여덟 개다. 설치·검증·초기화·첫 실행이 사실상 이 안에서 다 끝난다. --help를 치면 전체 명령이 그룹별로 쏟아지지만, 처음엔 이 여덟 개만 손에 익히면 된다.

npx ruflo@latest --help

npx ruflo@latest --help

이 여덟 개면 설치·검증·초기화·첫 실행까지 대부분 커버된다. 더 나아가면 hive-mind(Queen 주도 합의 기반 조율), neural(패턴 학습), security(보안 스캔) 같은 고급 명령이 있지만, 입문 단계에서는 위 표의 명령에 집중하자. 참고로 daemon은 주로 daemon start처럼 서브커맨드와 함께 쓰고, 각 명령의 세부 옵션은 ruflo <명령> --help로 언제든 확인할 수 있다. 전체 명령 레퍼런스는 ruflo 위키에 정리돼 있다.

다른 멀티 에이전트 도구와 뭐가 다른가 — orca·cmux·herdr

ruflo를 처음 보면 orca·cmux·herdr 같은 도구와 뭐가 다른지 헷갈린다. 핵심 차이는 “에이전트를 묶는 층위”다. ruflo는 한 Claude Code 안에서 역할이 나뉜 서브 에이전트(coder·reviewer·tester)를 스웜으로 조율하는 쪽이고, orca·cmux·herdr는 여러 Claude Code 인스턴스를 병렬로 띄우는 쪽이다. 둘 다 멀티 에이전트지만, 앞쪽은 한 작업을 팀으로 나눠 풀고 뒤쪽은 여러 작업을 동시에 굴린다.

이 블로그에서 다룬 병렬 실행 도구들을 보면 접근이 더 또렷해진다. Orca는 Git worktree 기반으로 여러 에이전트를 동시에 돌리고, cmux는 macOS 터미널에서 탭·분할 패널로, Herdr는 터미널 멀티플렉서로 Claude Code를 무리 지어 띄운다. 셋 다 인스턴스를 여러 개 나란히 두는 방식이라, 각 에이전트는 서로 독립적으로 각자 브랜치·작업을 맡는다. 반면 ruflo의 에이전트들은 한 스웜 안에서 공유 메모리로 서로의 결과를 주고받으며 협업한다.

표로 비교하면 다음과 같다.

표에서 보듯 선택 기준은 단순하다. 하나의 큰 작업을 역할 분담해 조율하고 싶으면 ruflo가, 여러 작업·브랜치를 각각 독립적으로 동시에 진행하고 싶으면 orca·cmux·herdr가 맞다. 세 도구의 계층 차이가 더 궁금하다면 터미널 도구 총정리 글에서 앱·멀티플렉서·오케스트레이터를 층별로 정리해 두었다. 참고로 둘은 배타적이지 않다. 여러 worktree를 orca로 띄우고 그 안에서 각각 ruflo 스웜을 돌리는 식으로 겹쳐 쓸 수도 있다. LangGraph·CrewAI·AutoGen 같은 범용 멀티 에이전트 프레임워크도 있지만, ruflo는 Claude Code에 바로 붙어 동작한다는 점에서 결이 다르다.

처음 쓸 때 자주 막히는 지점

ruflo 입문에서 가장 흔한 세 가지 걸림돌은 Node 버전, git 저장소 부재, 그리고 초기화를 건너뛰는 실수다. 먼저 Node는 반드시 20 이상이어야 한다. 블로그마다 18이라고 적힌 경우가 많은데, 실제 engines는 20을 요구하므로 18 환경이라면 먼저 Node를 올려야 한다. 버전 관리가 번거롭다면 nvm 같은 도구로 20으로 맞추면 된다.

둘째, git 저장소가 아닌 폴더에서 돌리면 doctor가 Git Repository: Not a git repository 경고를 띄운다. 치명적이진 않지만, ruflo의 변경 위험도 분석 등이 git 이력을 쓰므로 프로젝트를 git init으로 관리하는 걸 권한다. 셋째, init을 건너뛰고 swarm이나 status부터 치면 메모리 DB가 없다는 경고가 뜬다. 순서는 항상 doctor로 환경 확인 → init으로 초기화 → daemon/swarm으로 실행이다. 이 순서만 지켜도 입문 단계의 대부분 문제는 피해 간다.

FAQ

마치며

처음 ruflo를 깔았을 때 가장 당황스러웠던 건 명령이 너무 많다는 점이었다. --help를 쳤더니 init·swarm·memory는 물론이고 neural·security·hive-mind·federation까지 수십 개가 쏟아져서, “이걸 다 알아야 하나” 싶어 막막했다. 그런데 막상 입문에 필요한 건 doctor로 환경 보고, init으로 깔고, swarm으로 하나 띄워 보는 게 전부였다. 나머지는 쓰다가 필요할 때 하나씩 열어 보면 됐다.

특히 doctor가 고마웠다. 새 도구를 깔면 “내 환경이 맞나”부터 불안한데, ruflo는 Node 버전·Claude Code·인증 상태를 한 화면에 정리해 주니 첫 삽을 뜨기가 한결 수월했다. 멀티 에이전트라는 말이 거창하게 들리지만, 결국은 역할 나눈 조수 여럿을 한 번에 부리는 일이다. 처음엔 에이전트 한둘로 작게 시작해, 손에 익은 뒤 스웜을 키워 가길 권한다. 지금까지 ruflo 입문에 필요한 설치·설정·첫 실행을 정리해 보았다.