barehands 是一个基于摄像头的手势交互界面，把普通 Chrome 浏览器 + WebCam 变成“裸手控制”的 AR/空间看板。它使用 Google MediaPipe 做手部追踪，three.js 渲染 3D/玻璃卡片界面，支持用捏合、拖拽、双手缩放、挥动、拍手清屏、隔空抓取等手势操作笔记、图片和 3D 模型。项目还提供简单的本地协议，让 Claude Code、本地 LLM、脚本或任何能写文件/curl localhost 的程序把内容展示到看板上，适合做 AI 助手的可视化前端。
适用领域
人机交互 / 手势识别 / 增强现实 AR / AI 助手界面 / 浏览器 3D 可视化 / 创意编程 / Obsidian/Markdown 知识库可视化 / 直播/录屏工具 / 本地 AI 工作流
配置难度
中等。基础运行很简单，只需 Python、Chrome 和摄像头；但要稳定使用、接入 Claude Code/本地 LLM、配置 Obsidian vault、调优手势、适配 OBS 或改造为自己的产品，需要一定前端、脚本、AI Agent 和浏览器调试经验。
商业价值
适合用于 AI 助手可视化前端、交互式演示、直播内容创作、知识库空间化浏览和 AR/手势交互原型验证。对个人开发者和小团队而言，它能快速做出具有视觉冲击力的 AI 交互 Demo；对企业而言，可用于内部工具展示、研发原型、培训和创意场景。但由于 AGPL 许可证、CDN 依赖、手势稳定性和摄像头隐私合规问题，若要集成进闭源商业产品或大规模生产环境，需要额外评估授权、安全和工程化成本。
01
技术亮点
- 无需头显、控制器或手套，只用摄像头和 Chrome 即可实现手势控制。
- 安装门槛低，本地 Python 标准库服务器即可运行。
- 手势设计丰富，包括点击、捏合拖拽、双手缩放、抛掷、拍手清屏、隔空抓取、3D 爆炸视图拖拽等。
- 可以把普通 Markdown 文件夹或 Obsidian vault 直接作为看板内容源。
- AI 接入协议非常简单，基于文件状态和本地命令/localhost 请求，适合快速接入 Claude、本地 LLM、cron、Stream Deck 等。
- 支持 OBS 透明渲染、隐藏手指光标、超采样、竖屏和 4K 参数，适合内容创作。
- 内置安全机制，包括 action allowlist 和 media jail，降低 AI 误操作本地文件的风险。
- 技术栈轻量，主要依赖前端 CDN 上的 MediaPipe 和 three.js，易于理解和二次开发。
- 项目定位新颖，可作为 AI Agent 的空间 UI、演示工具或交互原型。
02
目标用户
- 希望为 AI 助手增加可视化交互界面的开发者
- 使用 Claude Code 或本地 LLM 的个人开发者
- 做 AI Agent、语音助手、空间 UI 原型的工程师
- Obsidian/Markdown 知识库重度用户
- 需要直播、教学、演示中展示手势控制界面的创作者
- 对 MediaPipe、three.js、Web AR 感兴趣的前端开发者
- 希望无头显、无控制器体验 AR/空间交互的创客
03
配置要求
- 硬件：需要可用摄像头，建议光线充足、摄像头视角能完整拍到手部。
- 浏览器：推荐 Chrome，因为项目依赖浏览器摄像头能力和前端运行 MediaPipe/three.js。
- 网络：首次运行会从公共 CDN 加载 Google MediaPipe 和 three.js，因此需要能访问相关 CDN；离线或受限网络环境可能无法正常启动。
- 运行环境：本地 Python 标准库服务器即可，不需要复杂后端依赖。
- 配置文件：barehands.json 用于配置 AI 名称、orbs、笔记目录、媒体目录等。
- 媒体安全限制：只有 media/ 目录内的文件能被展示到看板上，这是项目内置的安全隔离设计。
- AI 集成：AI 或脚本可以通过写入 state/state 控制 ring 状态，通过 bin/board.sh 发送展示动作，通过 bin/board-state.sh 读取看板状态。
- Claude Code 集成：需要在 Claude Code settings.json 中配置 hooks，或使用项目向导自动完成。
- 手势调优：如果识别不稳定，需要参考 TROUBLESHOOTING.md 使用 debug overlay 和 pose sampler 调整阈值。
04
适用场景
- 用手势在屏幕上移动、缩放、旋转笔记卡片、图片和 3D 模型
- 把 Obsidian vault 或普通 Markdown 文件夹作为可视化知识库浏览
- 让 AI 助手通过本地文件或 localhost API 把计划、图片、状态等内容展示到看板上
- 为 Claude Code 配置状态联动，让屏幕上的 ring 表示 AI 的 idle、thinking、listening、speaking 等状态
- 制作 AI Agent 的“脸”和“手”，作为本地工作流的空间化 UI
- 在 OBS 中作为透明叠加层，用于直播、教学视频、Shorts/TikTok 竖屏录制
- 演示 3D 模型爆炸视图、全息线框效果或交互式产品展示
- 研究和调试手势识别阈值、姿态采样和浏览器端交互体验
05
部署与配置
- 确保本机安装 Python 3，并使用 Chrome 浏览器。
- 克隆仓库：git clone https://github.com/jaredrhod/barehands
- 进入目录：cd barehands
- 启动本地服务器：python3 server.py；Windows 使用 python server.py
- 在 Chrome 打开 http://127.0.0.1:8794/stage.html
- 允许浏览器访问摄像头，然后挥手测试手势追踪。
- 如需接入自己的笔记或媒体，编辑 barehands.json，配置 orbs 中的 title、path、kind。
- 如需接入 Claude Code，可在 Claude Code 会话中让 agent 读取 barehands.md 并自动配置。
- 如需 OBS 透明渲染，可使用 stage.html?role=render，并按需要添加 cursors=0、ss=2、portrait=1、res=3840x2160 等参数。
06
风险与注意事项
- AGPL-3.0 许可证具有强 copyleft 属性，如果修改后对外分发或作为网络服务提供，通常需要开放相应源码；闭源商业产品需另行授权。
- 依赖公共 CDN 加载 MediaPipe 和 three.js，在中国大陆网络环境下可能遇到访问慢、失败或不稳定，需要自建镜像或改成本地资源。
- 手势识别效果受摄像头质量、光线、背景、手部遮挡和设备性能影响较大。
- README 宣称项目持续更新且手势修复频繁，API 和交互行为可能存在变化，需要关注更新说明。
- 项目语言标记为 HTML，可能更偏原型/前端脚本形态，工程化、测试覆盖、长期维护质量需要进一步查看源码确认。
- AI 可通过本地接口向看板发送动作，虽然有 allowlist 和媒体隔离，但仍需审查 server.py、脚本和配置，避免暴露到非本机网络。
- 摄像头权限涉及隐私，企业环境落地前需要明确数据是否完全本地处理、浏览器加载的第三方脚本是否符合安全要求。
- 中文文档和中文社区支持可能有限，中国开发者需要自行阅读英文文档和调试。
2026-08-21
第28名
新收录 · github_search
