Hướng dẫn VibeClaude: Kết nối sự kiện Claude Code với thiết bị Intiface

VibeClaude làm gì

VibeClaude là một plugin Claude Code, chuyển hoạt động lập trình thành phản hồi từ thiết bị thông qua Intiface Central và buttplug.io. Các sự kiện Claude Code được gửi đến một daemon cục bộ. Daemon này giao tiếp với Intiface Central qua WebSocket, sau đó điều khiển một thiết bị hỗ trợ rung đã ghép nối.

Claude Code — mô-đun hooks — HTTP — daemon — WebSocket — Intiface Central — BLE — thiết bị

Plugin phản hồi với đầu ra mô hình dạng luồng, các lệnh gọi công cụ, lời nhắc cấp quyền, todo đã hoàn tất, tác nhân phụ, thao tác gián đoạn, cùng các sự kiện vòng lặp hoặc vòng đời phiên. Plugin được thiết kế cho không gian riêng tư, thoải mái; bạn nên sử dụng phần cứng tương thích một cách có trách nhiệm.

Yêu cầu

• Claude Code có hỗ trợ plugin function-hooks. VibeClaude được xây dựng dựa trên phiên bản 2.1.291 của API đang trong giai đoạn truy cập sớm này.
• Node.js 22 trở lên, có sẵn dưới tên node trong PATH.
• Intiface Central đang chạy máy chủ WebSocket. Địa chỉ mặc định là ws://127.0.0.1:12345.
• Một bộ điều khiển hỗ trợ rung đã được ghép nối trong Intiface Central.
• Một môi trường riêng tư phù hợp để sử dụng thiết bị đã kết nối.

Cài đặt VibeClaude

Sao chép kho lưu trữ vào thư mục cấu hình Claude rồi cài đặt các dependency:

git clone https://github.com/transkatgirl/vibeclaude.git ~/.claude/vibeclaude
cd ~/.claude/vibeclaude && npm install

Bạn có thể tải plugin cho một phiên Claude Code bằng lệnh:

claude --plugin-dir ~/.claude/vibeclaude

Hoặc cài đặt vĩnh viễn từ bên trong Claude Code:

/plugin marketplace add ~/.claude/vibeclaude
/plugin install vibeclaude@vibeclaude-local

Khởi động lại Claude Code sau khi cài đặt. Plugin sẽ được tải khi một phiên mới bắt đầu.

Kiểm tra vị trí dependency

Daemon chạy từ thư mục mà Claude Code dùng để tải plugin và yêu cầu thư mục node_modules nằm tại đó. Các plugin được cài qua marketplace có thể được sao chép vào một vị trí không chứa dependency đã cài trong bản sao kho lưu trữ ban đầu của bạn.

Nếu Claude Code hiển thị thông báo thiếu gói npm buttplug, hãy chạy npm install trong thư mục được nêu trong thông báo.

Kết nối thiết bị

1. Khởi động Intiface Central và nhấn nút khởi động máy chủ.
2. Trong Claude Code, chạy /intiface.
3. Chờ quá trình kết nối và quét hoàn tất.
4. Chọn một thiết bị hỗ trợ rung từ kết quả.
5. Bắt đầu sử dụng Claude Code sau khi xác nhận thiết bị đã kết nối và phù hợp với môi trường của bạn.

Lệnh /intiface mở một hộp thoại hiển thị trạng thái kết nối và quét. Dùng các phím mũi tên hoặc Tab để di chuyển qua các thiết bị, nhấn Enter hoặc nhấp chuột để chọn, và nhấn Escape để rời hộp thoại.

Không có dữ liệu nào được gửi đến thiết bị cho đến khi bạn chọn một thiết bị. VibeClaude chỉ điều khiển chính xác một thiết bị đã chọn tại mỗi thời điểm. Khi một phiên Claude Code mới bắt đầu, plugin sẽ cố gắng kết nối lại với Intiface Central và khôi phục thiết bị đã chọn trước đó nếu thiết bị vẫn khả dụng.

Các lệnh của plugin

• /intiface: Kết nối với Intiface, quét thiết bị và chọn một thiết bị.
• /intiface-connect: Kết nối với máy chủ Intiface đã cấu hình và khôi phục thiết bị đã chọn trước đó nếu có.
• /intiface-disconnect: Ngắt kết nối và dừng mọi đầu ra từ thiết bị.
• /intiface-intensity [0.0-1.0]: Đặt hệ số cường độ toàn cục hoặc báo cáo giá trị hiện tại khi không cung cấp số.

Các lệnh này chạy bên trong plugin mà không bắt đầu một lượt mô hình hay tiêu tốn token. Chúng cũng không để lại đầu ra lệnh trong cuộc trò chuyện và có thể được sử dụng khi một lượt đang chạy.

Tìm hiểu các kiểu phản hồi

VibeClaude biểu diễn mỗi sự kiện dưới dạng một kiểu có thời lượng cố định và cường độ không đổi. Trong một cuộc trò chuyện, sự kiện mới nhất sẽ thay thế sự kiện trước đó. Hệ số cường độ toàn cục được áp dụng sau khi sự kiện được chọn.

• Suy nghĩ và văn bản dạng luồng: Một xung 70 mili giây cho mỗi phần, với cường độ từ 0.35 đến 0.8 dựa trên tốc độ đầu ra trung bình. Phép tính tốc độ phản hồi đạt ngưỡng bão hòa ở 40 ký tự mỗi giây.
• Phản hồi hoàn chỉnh: Một xung 150 mili giây ở mức 0.4 khi phản hồi đến mà không qua dạng luồng.
• Lệnh gọi công cụ: Một xung 120 mili giây ở mức 0.5 khi mô hình bắt đầu viết lệnh gọi công cụ.
• Thao tác chỉnh sửa: Giữ rung liên tục ở mức 0.3 trong khi thao tác Edit, Write, MultiEdit hoặc NotebookEdit được viết và áp dụng.
• Lệnh gọi công cụ thành công: Một xung 180 mili giây ở mức 0.7.
• Lệnh gọi công cụ thất bại, bị từ chối hoặc bị bác bỏ: Một xung 280 mili giây ở mức 1.0.
• Mục todo hoàn tất: Một xung ở mức 0.8, ngay lập tức được thay thế bằng kiểu thành công của công cụ.
• Lời nhắc cấp quyền: Ba xung 90 mili giây ở mức 0.85, sau đó tạm dừng và lặp lại cho đến khi lời nhắc được xử lý.
• Hoàn tất lượt: Ba xung 100 mili giây ở mức 1.0.
• Lượt bị gián đoạn hoặc thất bại: Dừng đầu ra hiện tại, sau đó phát ba xung được dùng khi hoàn tất lượt.
• Kết thúc phiên: Dừng mọi đầu ra.

Nhiều phiên và tác nhân phụ

Mỗi phiên Claude Code đang mở theo dõi các công cụ, lời nhắc, todo và tác nhân phụ riêng. Khi có nhiều kiểu đang hoạt động, kiểu mạnh nhất sẽ được sử dụng. Khi kiểu đó kết thúc, thiết bị có thể quay lại một kiểu đang hoạt động từ phiên khác.

Các tiến trình con được trộn vào cuộc hội thoại đã khởi chạy chúng. Đầu ra được truyền theo luồng, các lệnh gọi công cụ, lời nhắc cấp quyền, danh sách việc cần làm và các sự kiện hoàn tất hoặc thất bại của chúng được biểu diễn độc lập. Kết thúc phiên chính sẽ dừng tất cả tiến trình con của phiên đó.

Điều chỉnh cường độ

Sử dụng lệnh cường độ để giảm hoặc tắt đầu ra:

/intiface-intensity 0.5

Hệ số mặc định là 1.0. Giá trị 0 sẽ tắt phản hồi, còn các giá trị từ 0 đến 1 sẽ điều chỉnh tỷ lệ của mọi mẫu đang hoạt động. Thay đổi có hiệu lực ngay lập tức, kể cả với mẫu đang phát, và được lưu cho đến khi bạn thay đổi.

Hạn chế quan trọng của sự kiện

Một số hành vi nhất thiết chỉ mang tính gần đúng do thông tin mà Claude Code cung cấp cho các plugin:

• Suy nghĩ: Suy nghĩ chỉ được biểu diễn ở nơi Claude Code hiển thị văn bản đó. Ví dụ, suy nghĩ không khả dụng trong một lần chạy claude -p không tương tác.
• Phản hồi cấp quyền: Claude Code không báo cáo chính xác thời điểm lời nhắc cấp quyền được trả lời. Mẫu lời nhắc thường kết thúc khi công cụ liên quan hoàn tất, thất bại hoặc bị từ chối. Một số gợi ý chạy terminal ở chế độ nền có thể khiến mẫu dừng sớm hơn.
• Đầu ra công cụ: Plugin không nhận được đầu ra lệnh trong khi đầu ra đang được truyền, vì vậy đầu ra công cụ được biểu diễn bằng kết quả công cụ thay vì từng dòng được in ra.

Cấu hình plugin

Claude Code yêu cầu các tùy chọn plugin khi bạn bật plugin. Bạn có thể thay đổi chúng sau đó thông qua /plugin và giao diện quản lý plugin.

• wsAddress: Địa chỉ WebSocket của Intiface Central. Giá trị mặc định là ws://127.0.0.1:12345.

Địa chỉ WebSocket mới sẽ có hiệu lực vào lần daemon khởi động tiếp theo. Hãy kết thúc các phiên của bạn hoặc dừng daemon trực tiếp bằng lệnh:

node daemon/daemon.mjs stop

VibeClaude lưu thiết bị đã chọn, cường độ và daemon.log trong ~/.config/vibeclaude. Nếu cổng TCP 12350 đã được sử dụng, hãy tạo ~/.config/vibeclaude/config.json với một cổng khác:

{ "port": 12351 }

Sử dụng daemon từ shell

Daemon có thể được điều khiển độc lập với các lệnh slash của Claude Code. Các lệnh này sử dụng thư mục cấu hình và địa chỉ WebSocket mặc định:

• node daemon/daemon.mjs scan: Kết nối, quét trong ba giây và liệt kê các thiết bị có khả năng rung.
• node daemon/daemon.mjs select <index>: Chọn một thiết bị từ kết quả quét.
• node daemon/daemon.mjs connect và disconnect: Kết nối hoặc ngắt kết nối với Intiface.
• node daemon/daemon.mjs intensity [value]: Đặt hoặc hiển thị hệ số cường độ.
• node daemon/daemon.mjs start: Đảm bảo daemon đang chạy và in ra cổng của daemon.
• node daemon/daemon.mjs status: Kiểm tra daemon có phản hồi hay không.
• node daemon/daemon.mjs stop: Dừng mọi đầu ra và thoát daemon.
• node daemon/daemon.mjs: Chạy daemon ở chế độ tiền cảnh.

Sử dụng --home <dir> để chọn một thư mục cấu hình khác và --ws <address> để chỉ định địa chỉ Intiface khác. Để ghi nhật ký mọi sự kiện ngay khi chúng đến, hãy đặt biến môi trường debug:

VIBECLAUDE_DEBUG=1 node daemon/daemon.mjs

Kiểm thử không cần phần cứng

Kho mã nguồn có một máy chủ Intiface mô phỏng, máy chủ này in ra mức động cơ mà nó lẽ ra đã nhận được. Khởi động máy chủ trên cổng 12345:

node test/mock-intiface.mjs 12345

Sau đó chạy bộ kiểm thử:

npm test

Các bài kiểm thử kiểm tra daemon từ đầu đến cuối với máy chủ mô phỏng và kiểm thử mô-đun hooks, giúp bạn kiểm tra cài đặt mà không cần bộ điều khiển vật lý.

Kiến trúc hoạt động như thế nào

hooks/register.tsx chạy bên trong Claude Code. Mô-đun này theo dõi các sự kiện hook như các bước của lượt được truyền theo luồng, lệnh gọi công cụ, kiểm tra cấp quyền, tạo tiến trình con và các thay đổi trong vòng đời phiên hoặc lượt. Mô-đun rút gọn các sự kiện đó thành những thông báo nhỏ chứa kích thước và mã định danh thay vì văn bản của mô hình, sau đó gửi chúng theo đúng thứ tự đến daemon tại địa chỉ loopback 127.0.0.1:12350.

Mô-đun hooks cũng đăng ký các lệnh slash, hiển thị hộp thoại chọn thiết bị và hiển thị thông báo của daemon dưới dạng thông báo nhanh. Vì mô-đun hooks không có quyền truy cập Node.js, nó không thể tự chạy ứng dụng khách Buttplug hoặc duy trì kết nối WebSocket với Intiface.

daemon/daemon.mjs xử lý ứng dụng khách Buttplug chính thức, kết nối Intiface, thiết bị được chọn, công cụ rung và các trình xử lý sự kiện. Vì thiết bị có thể phản hồi chậm hơn tốc độ đầu ra của mô hình, daemon gửi mức mới nhất được yêu cầu thay vì tạo một hàng đợi tồn đọng.

Daemon khởi động khi phiên đầu tiên cần đến nó và thoát sau khi phiên cuối cùng kết thúc. Daemon theo dõi tiến trình Claude Code được liên kết với từng phiên và có thể dọn dẹp các phiên biến mất bất ngờ. Nếu không xác định được tiến trình nào đã kết thúc, daemon sẽ thoát sau 30 phút không hoạt động.

Quyền riêng tư và tự động tắt

Plugin chỉ gửi lệnh thiết bị đến địa chỉ Intiface được cấu hình trên máy của bạn. Daemon lắng nghe trên loopback và chấp nhận các yêu cầu JSON được gửi đến 127.0.0.1 hoặc localhost; daemon không cung cấp dịch vụ mạng cho các trang trình duyệt. VibeClaude không có telemetry.

Đầu ra sẽ tự động dừng khi bạn chuyển thiết bị, kết thúc phiên, ngắt kết nối, mất kết nối Intiface hoặc daemon thoát. Nếu thiết bị ngắt kết nối khỏi Intiface, thiết bị sẽ bị bỏ chọn; hãy sử dụng /intiface để kết nối lại. Một thiết bị tạm thời biến mất có thể được chọn lại khi xuất hiện trở lại.

Kết luận

VibeClaude kết nối các hook của Claude Code với Intiface Central thông qua một daemon Node.js cục bộ, biến các sự kiện lập trình thành phản hồi thiết bị có thể cấu hình. Cài đặt plugin và các phần phụ thuộc, khởi động Intiface Central, chọn thiết bị bằng /intiface và điều chỉnh trải nghiệm với /intiface-intensity. Để khắc phục sự cố và phát triển, hãy sử dụng các lệnh daemon shell, tính năng ghi nhật ký gỡ lỗi và máy chủ giả lập đi kèm.

Dự án được cấp phép theo Giấy phép MIT. Buttplug và Intiface là các nhãn hiệu của Nonpolynomial Labs, LLC.