VibeClaude의 기능
VibeClaude는 Intiface Central 및 buttplug.io를 통해 코딩 활동을 기기 피드백으로 변환하는 Claude Code 플러그인입니다. Claude Code 이벤트는 로컬 데몬으로 전송되고, 데몬은 WebSocket을 통해 Intiface Central과 통신한 다음 연결된 진동 지원 기기를 제어합니다.
Claude Code — hooks module — HTTP — daemon — WebSocket — Intiface Central — BLE — device이 플러그인은 스트리밍 모델 출력, 도구 호출, 권한 요청, 완료된 할 일, 하위 에이전트, 중단, 턴 또는 세션 수명 주기 이벤트에 반응합니다. 개인적이고 편안한 환경에서 사용하도록 설계되었으며, 호환되는 하드웨어를 책임감 있게 사용해야 합니다.
요구 사항
- function-hooks 플러그인을 지원하는 Claude Code. VibeClaude는 이 얼리 액세스 API의 2.1.291 버전을 기준으로 제작되었습니다.
PATH에서node로 사용할 수 있는 Node.js 22 이상.- WebSocket 서버가 실행 중인 Intiface Central. 기본 주소는
ws://127.0.0.1:12345입니다. - Intiface Central에 연결된 진동 지원 컨트롤러.
- 연결된 기기를 사용하기에 적합한 개인 환경.
VibeClaude 설치
Claude 설정 디렉터리에 저장소를 복제하고 종속 항목을 설치합니다.
git clone https://github.com/transkatgirl/vibeclaude.git ~/.claude/vibeclaude
cd ~/.claude/vibeclaude && npm install다음 명령으로 하나의 Claude Code 세션에 플러그인을 로드할 수 있습니다.
claude --plugin-dir ~/.claude/vibeclaude또는 Claude Code 내부에서 영구적으로 설치할 수 있습니다.
/plugin marketplace add ~/.claude/vibeclaude
/plugin install vibeclaude@vibeclaude-local설치 후 Claude Code를 다시 시작합니다. 새 세션이 시작될 때 플러그인이 로드됩니다.
종속 항목 위치 확인
데몬은 Claude Code가 플러그인을 로드하는 디렉터리에서 실행되며, 해당 위치에 node_modules 디렉터리가 있어야 합니다. 마켓플레이스에서 설치한 플러그인은 원래 복제본에서 설치한 종속 항목이 없는 위치로 복사될 수 있습니다.
Claude Code에 buttplug npm 패키지가 없다는 메시지가 표시되면, 메시지에 지정된 디렉터리에서 npm install을 실행합니다.
기기 연결
- Intiface Central을 시작하고 서버 시작 버튼을 누릅니다.
- Claude Code에서
/intiface를 실행합니다. - 연결 및 검색이 완료될 때까지 기다립니다.
- 결과에서 진동 지원 기기를 선택합니다.
- 기기가 연결되었고 현재 환경에 적합한지 확인한 후 Claude Code를 사용합니다.
/intiface 명령은 연결 및 검색 상태를 보여 주는 대화 상자를 엽니다. 화살표 키 또는 Tab 키로 기기 목록을 이동하고, Enter 키를 누르거나 클릭하여 선택하며, Escape 키를 눌러 대화 상자를 닫습니다.
기기를 선택하기 전에는 어떤 기기에도 아무것도 전송되지 않습니다. VibeClaude는 한 번에 선택한 기기 하나만 제어합니다. 이후 Claude Code 세션이 시작되면 플러그인은 Intiface Central에 다시 연결하고, 이전에 선택한 기기를 사용할 수 있는 경우 복원하려고 시도합니다.
플러그인 명령
/intiface: Intiface에 연결하고 기기를 검색한 후 기기를 선택합니다./intiface-connect: 구성된 Intiface 서버에 연결하고, 사용 가능한 경우 이전에 선택한 기기를 복원합니다./intiface-disconnect: 연결을 끊고 모든 기기 출력을 중지합니다./intiface-intensity [0.0-1.0]: 전역 강도 배율을 설정하거나, 숫자를 입력하지 않으면 현재 값을 표시합니다.
이 명령은 모델 턴을 시작하거나 토큰을 소비하지 않고 플러그인 내부에서 실행됩니다. 또한 대화에 명령 출력을 남기지 않으며 턴이 실행 중일 때도 사용할 수 있습니다.
피드백 패턴 이해
VibeClaude는 각 이벤트를 일정한 강도의 고정 지속 시간 패턴으로 표현합니다. 하나의 대화에서는 가장 최근 이벤트가 이전 이벤트를 대체합니다. 전역 강도 배율은 이벤트를 선택한 후 적용됩니다.
- 스트리밍 사고 및 텍스트: 각 조각마다 70밀리초의 펄스를 출력하며, 평균 출력 속도에 따라 강도는 0.35에서 0.8 사이로 설정됩니다. 응답 속도 계산은 초당 40자에서 포화됩니다.
- 전체 응답: 스트리밍 없이 응답이 도착하면 강도 0.4로 150밀리초의 펄스를 출력합니다.
- 도구 호출: 모델이 도구 호출 작성을 시작하면 강도 0.5로 120밀리초의 펄스를 출력합니다.
- 편집 작업:
Edit,Write,MultiEdit또는NotebookEdit작업이 작성되고 적용되는 동안 강도 0.3으로 계속 유지합니다. - 성공한 도구 호출: 강도 0.7로 180밀리초의 펄스를 출력합니다.
- 실패, 거부 또는 승인되지 않은 도구 호출: 강도 1.0으로 280밀리초의 펄스를 출력합니다.
- 완료된 할 일 항목: 강도 0.8의 펄스를 출력한 직후 도구 성공 패턴으로 대체됩니다.
- 권한 요청: 강도 0.85로 90밀리초의 펄스를 세 번 출력한 후 잠시 멈추며, 요청이 처리될 때까지 반복합니다.
- 턴 완료: 강도 1.0으로 100밀리초의 펄스를 세 번 출력합니다.
- 중단되거나 실패한 턴: 현재 출력을 중지한 후 턴 완료에 사용되는 세 번의 펄스를 출력합니다.
- 세션 종료: 모든 출력을 중지합니다.
여러 세션 및 하위 에이전트
열려 있는 각 Claude Code 세션은 자체 도구, 요청, 할 일 및 하위 에이전트를 추적합니다. 여러 패턴이 활성화되어 있으면 가장 강한 패턴이 사용됩니다. 해당 패턴이 종료되면 기기는 다른 세션의 활성 패턴으로 돌아갈 수 있습니다.
서브에이전트는 해당 에이전트를 시작한 대화에 함께 표시됩니다. 서브에이전트의 스트리밍 출력, 도구 호출, 권한 요청, 할 일 목록, 완료 또는 실패 이벤트는 각각 독립적으로 표시됩니다. 기본 세션을 종료하면 모든 서브에이전트가 중지됩니다.
강도 조정
출력을 줄이거나 비활성화하려면 강도 명령을 사용하세요.
/intiface-intensity 0.5기본 배율은 1.0입니다. 0은 피드백을 비활성화하고, 0과 1 사이의 값은 현재 활성화된 모든 패턴의 강도를 조정합니다. 변경 사항은 즉시 적용되며, 이미 재생 중인 패턴에도 적용되고, 다시 변경할 때까지 저장됩니다.
중요한 이벤트 제한 사항
Claude Code가 플러그인에 제공하는 정보에는 한계가 있으므로 일부 동작은 필연적으로 근사값으로 처리됩니다.
- 사고: 사고 내용은 Claude Code가 텍스트를 표시하는 경우에만 표시됩니다. 예를 들어 헤드리스
claude -p실행 중에는 사고 내용을 사용할 수 없습니다. - 권한 응답: Claude Code는 권한 요청에 응답한 정확한 시점을 보고하지 않습니다. 일반적으로 관련 도구가 완료되거나 실패하거나 거부되면 요청 패턴이 종료됩니다. 일부 터미널의 백그라운드 실행 힌트는 패턴을 더 일찍 중지할 수 있습니다.
- 도구 출력: 플러그인은 명령 출력을 스트리밍되는 동안 수신하지 않으므로, 도구 출력은 각 출력 줄이 아니라 도구 결과로 표시됩니다.
플러그인 구성
플러그인을 활성화하면 Claude Code가 플러그인 옵션을 묻습니다. 나중에 /plugin과 플러그인 관리 인터페이스를 통해 옵션을 변경할 수 있습니다.
wsAddress: Intiface Central WebSocket 주소입니다. 기본값은ws://127.0.0.1:12345입니다.
변경한 WebSocket 주소는 데몬이 다음에 시작될 때 적용됩니다. 세션을 종료하거나 다음 명령으로 데몬을 직접 중지하세요.
node daemon/daemon.mjs stopVibeClaude는 선택한 장치, 강도, daemon.log를 ~/.config/vibeclaude에 저장합니다. TCP 포트 12350이 이미 사용 중이면 다른 포트를 지정한 ~/.config/vibeclaude/config.json 파일을 생성하세요.
{ "port": 12351 }셸에서 데몬 사용
Claude Code 슬래시 명령과 별개로 데몬을 제어할 수 있습니다. 다음 명령은 기본 구성 디렉터리와 WebSocket 주소를 사용합니다.
node daemon/daemon.mjs scan: 연결하고 3초 동안 검색한 다음 진동을 지원하는 장치를 나열합니다.node daemon/daemon.mjs select <index>: 검색 결과에서 장치를 선택합니다.node daemon/daemon.mjs connect및disconnect: Intiface에 연결하거나 연결을 해제합니다.node daemon/daemon.mjs intensity [value]: 강도 배율을 설정하거나 표시합니다.node daemon/daemon.mjs start: 데몬이 실행 중인지 확인하고 포트를 출력합니다.node daemon/daemon.mjs status: 데몬이 응답하는지 확인합니다.node daemon/daemon.mjs stop: 모든 출력을 중지하고 데몬을 종료합니다.node daemon/daemon.mjs: 데몬을 포그라운드에서 실행합니다.
다른 구성 디렉터리를 선택하려면 --home <dir>를 사용하고, 다른 Intiface 주소를 지정하려면 --ws <address>를 사용하세요. 모든 이벤트가 도착하는 즉시 로그에 기록되도록 하려면 디버그 환경 변수를 설정하세요.
VIBECLAUDE_DEBUG=1 node daemon/daemon.mjs하드웨어 없이 테스트
저장소에는 수신했을 모터 레벨을 출력하는 모의 Intiface 서버가 포함되어 있습니다. 포트 12345에서 서버를 시작하세요.
node test/mock-intiface.mjs 12345그런 다음 테스트 모음을 실행하세요.
npm test테스트는 모의 서버를 대상으로 데몬을 종단 간 테스트하고 hooks 모듈도 테스트하므로, 실제 컨트롤러 없이 설치를 확인할 수 있습니다.
아키텍처 작동 방식
hooks/register.tsx는 Claude Code 내부에서 실행됩니다. 스트리밍 턴 단계, 도구 호출, 권한 확인, 서브에이전트 생성, 세션 또는 턴 수명 주기 변경과 같은 후크 이벤트를 관찰합니다. 그런 다음 이벤트를 모델 텍스트가 아닌 크기와 식별자를 포함한 작은 메시지로 변환하고, 루프백 주소 127.0.0.1:12350의 데몬에 순서대로 전송합니다.
hooks 모듈은 슬래시 명령도 등록하고, 장치 선택 대화 상자를 표시하며, 데몬 알림을 토스트로 표시합니다. hooks 모듈에는 Node.js 액세스 권한이 없으므로 Buttplug 클라이언트를 실행하거나 Intiface WebSocket 연결을 직접 유지할 수 없습니다.
daemon/daemon.mjs는 공식 Buttplug 클라이언트, Intiface 연결, 선택한 장치, 진동 엔진, 이벤트 핸들러를 처리합니다. 장치가 모델 출력보다 느리게 응답할 수 있으므로 데몬은 요청을 대기열에 쌓는 대신 가장 최근에 요청된 레벨을 전송합니다.
첫 번째 세션에서 데몬이 필요해지면 데몬이 시작되고, 마지막 세션이 종료되면 종료됩니다. 데몬은 각 세션과 연결된 Claude Code 프로세스를 모니터링하며, 예기치 않게 사라진 세션을 정리할 수 있습니다. 종료된 프로세스를 확인할 수 없는 경우에는 활동이 30분 동안 없으면 종료하는 방식으로 대체합니다.
개인정보 보호 및 자동 종료
플러그인은 사용자의 컴퓨터에 구성된 Intiface 주소로만 장치 명령을 전송합니다. 데몬은 루프백에서 수신하며 127.0.0.1 또는 localhost로 지정된 JSON 요청을 받습니다. 브라우저 페이지용 네트워크 서비스는 노출하지 않습니다. VibeClaude에는 텔레메트리가 포함되어 있지 않습니다.
장치를 전환하거나, 세션을 종료하거나, 연결을 해제하거나, Intiface 연결이 끊기거나, 데몬이 종료되면 출력이 자동으로 중지됩니다. 장치가 Intiface에서 연결 해제되면 선택이 해제됩니다. 다시 연결하려면 /intiface를 사용하세요. 일시적으로 사라진 장치는 다시 나타났을 때 재선택할 수 있습니다.
결론
VibeClaude는 Claude Code 훅을 로컬 Node.js 데몬을 통해 Intiface Central에 연결하여 코딩 이벤트를 구성 가능한 기기 피드백으로 변환합니다. 플러그인과 종속 항목을 설치하고 Intiface Central을 시작한 다음 /intiface로 기기를 선택하고 /intiface-intensity로 사용 환경을 조정하세요. 문제 해결과 개발을 위해 셸 데몬 명령, 디버그 로깅, 포함된 모의 서버를 사용할 수 있습니다.
이 프로젝트는 MIT 라이선스에 따라 제공됩니다. Buttplug와 Intiface는 Nonpolynomial Labs, LLC의 상표입니다.