barehands README

The project's README from github.com/jaredrhod/barehands. As one markdown file: README.md.

barehands

Never used Claude Code? Start at jaredrhod.com: pick your situation and it routes you to the right path.

Runs on: a webcam and Chrome; works with any AI. Any program that writes a file or curls localhost can be its brain.

Move things on your screen with your bare hands. barehands turns your webcam into a hand-tracked interface: notes, images, and 3D models float over your camera as glass cards. You pinch them, throw them, stretch them, force-pull them across the room, and blow an engine apart into its exploded view with a drag of two fingers. No headset. No controllers. No gloves. Bare hands.

And it's a body waiting for a brain: wire in your AI and the on-screen ring becomes its face, while two small scripts give it hands and eyes on your board. Free to use, change, and build on, including commercially inside your own business, and if you pass your version on it stays open under the same license (see LICENSE).

Watch it in action:

barehands demo video

Run it (nothing needed)

git clone https://github.com/jaredrhod/barehands
cd barehands
python3 server.py

On Windows run run.bat instead: a clean Windows 11 has no Python but leaves a Microsoft Store stub on the PATH that looks like one, and run.bat finds an interpreter that actually works. Open http://127.0.0.1:8794/stage.html in Chrome, allow the camera, and wave. That's the whole install: the server is stdlib Python, and the page loads its hand tracking (Google MediaPipe) and 3D (three.js) from CDNs on first run.

Already in a Claude Code session with your agent? One sentence does it all: "clone https://github.com/jaredrhod/barehands.git, then read barehands/barehands.md and set me up." Your agent installs it, configures it, and wires itself in.

Tap the ring → orbs bloom → tap an orb → your files unfold on glass. The sample notes teach the gestures from inside the board itself.

Give it your notes

The "vault" on the board is just a folder of markdown, which means an Obsidian vault works as-is, and so does any folder of .md files. Point an orb at it in barehands.json:

{
  "name": "Assistant",
  "orbs": [
    { "title": "Notes", "path": "~/MyVault", "kind": "notes" },
    { "title": "Props", "path": "media",               "kind": "media" }
  ]
}

One line per orb. Add more folders, rename them, point them anywhere. The media orb is the props airlock: drop images in media/misc/, transparent props in media/fx/, 3D models in media/models/, or in media/holo/, where the same model renders as a blue hologram wireframe. Only files inside media/ can ever appear on the board; that jail is a safety feature.

Wire in your AI

The easy way: open the repo in Claude Code and say "read barehands.md and set me up." The setup wizard interviews you, writes the config, and wires your assistant in end to end.

The manual way: barehands speaks two dead-simple protocols:

Anything that can write a file or curl localhost can be the brain: Claude, a local LLM, a cron job, a Stream Deck button.

If your assistant doesn't have a memory yet, pair this with ai-memory-vault; the vault it builds becomes a notes orb on this board.

The gestures

Tap (quick pinch) opens and closes. Pinch-drag moves. Hold still while carrying to rotate in 3D. Two hands scale. Flick to throw. Clap (palms together, fingers up) sweeps the board clean. The claw: flash your hand open, claw, aim at something across the screen, let it strain and shake for two seconds, then snap the claw shut, and it rips through the air into your hand. An empty pinch dragged sideways scrubs a 3D model's exploded view apart and back together.

Every threshold was tuned on a real hand across weeks of live use, and because the gates measure hand shape as ratios, not size, they hold at any camera distance. The full cheat sheet is on the board: Getting Started → The Gestures. If a gesture ever misfires for your hand or setup, TROUBLESHOOTING.md ships the tuning clinic: the built-in debug overlay and pose sampler, plus the exact method for your AI to fit the gates to your hand.

Streaming / recording (advanced)

Two pages, one scene: the tracker page owns your camera; stage.html?role=render is a truly transparent mirror of it, built for an OBS browser source: the glass composites over your camera feed with real alpha. &cursors=0 hides the finger rings (bare-hands sorcery), &ss=2 renders at 2× for razor-sharp cards, and ?portrait=1 on the tracker flips the whole rig to vertical 9:16 for Shorts and TikTok. ?res=3840x2160 bumps the tracker's capture for a 4K self-view (1280x720 rescues slow machines); in an OBS rig your broadcast camera is OBS's own source, so tracking happily stays at the default. Details in the sample notes' Field Guide.

Credits

Hand tracking by Google MediaPipe (Apache 2.0). 3D rendering by three.js (MIT). Both load from public CDNs; this repo redistributes neither.

Updating

barehands improves continuously, and gesture fixes ship often. To update on macOS, double-click the Update icon setup left on your Desktop, or run ./update.sh in this folder. On Windows, or any time, say "pull the latest barehands and tell me what changed" to your agent — it does the same job. Your config, your notes, and your media stay untouched: they live outside the tracked files. Installed through fullstack-agent? ./fullstack-agent/update.sh (macOS) updates every piece at once and prints what changed.

The rest of it

A board is better with an agent behind it. Give it a voice and you can talk while you move things around, and a memory vault turns the notes orb into your agent's actual brain instead of a folder of files.

Support

Free to use, and always will be. If this helped you out, you can buy me a coffee:

Support me on Ko-fi

License

Copyright (c) 2026 Jared Rhodenizer.

Licensed under the GNU Affero General Public License, version 3 or later (AGPL-3.0-or-later). Use it in your business, commercially, for free. Run it, change it, build your workflow on top of it, and charge for the work you do with it. The one rule is that it stays open: if you hand it to someone else, or run a modified version as a service other people use, your version ships under this same license with its source available. Credit me when you build on it. Want it inside a closed-source commercial product? Email [email protected]. Full terms are in the LICENSE file and at https://www.gnu.org/licenses/agpl-3.0.html

barehands (jaredrhod/barehands)

Searching Database…

1.1K ·GitHub
Barehands
What is this?Barehands turns your webcam into a hand-tracked interface for an AI: notes, images, and 3D models float over your camera feed as glass cards that you pinch, throw, stretch, and explode apart with your bare hands, no headset or controllers required.
Is this a native app or something that runs in the browser?It is a lightweight local web app: a stdlib-Python server serves a page you open in Chrome, and the page pulls hand tracking (Google MediaPipe) and 3D rendering (three.js) from CDNs on first run.
How do I get it running?Clone the repo and run the included script (run.bat on Windows); open the page in Chrome, allow the camera, and start waving. If you are already in a Claude Code session, just say 'clone then read barehands/barehands.md and set me up' and the agent installs and configures it for you.
Do I need Python or anything else installed first?No separate install: the server is just stdlib Python (run.bat handles Windows' fake Python stub for you), and hand tracking and 3D libraries load from public CDNs on first run, so you need internet at least once.
Does hand tracking always work reliably?Gesture thresholds were tuned on a real hand over weeks of use and measure hand shape as ratios rather than size, so they should hold at different camera distances, but if a gesture misfires for your hand or setup, TROUBLESHOOTING.md includes a debug overlay, pose sampler, and a method for your AI to re-tune the gates.
How do I connect my AI to control the board?In Claude Code, saying 'read barehands.md and set me up' runs a wizard that writes config and pastes two hooks into settings.json so the on-screen ring mirrors your sessions. Manually, any program can write to a tiny state file or curl bin/board.sh to stage cards, with the server enforcing an action allowlist and a media-folder jail for safety.
How do I add my own notes or files to the board?Point an orb at any folder of markdown files in barehands.json — an existing Obsidian vault works as-is. Images, transparent props, and 3D models (including hologram-wireframe renders) go in subfolders under media/, which is the only place the board will ever pull files from.
What gestures does it understand?Tap opens/closes a card, pinch-drag moves it, holding still while carrying rotates it in 3D, two hands scale it, flicking throws it, clapping sweeps the whole board clean, and a two-second 'claw' grab yanks a distant object into your hand; an empty sideways pinch-drag scrubs a 3D model's exploded view.
What's the catch with the AGPL license?You can use, modify, and even sell services built on barehands for free, including commercially, but if you hand your version to someone else or run a modified version as a service for others, that version must stay open-source under the same AGPL-3.0 license.
What are similar projects?AR.js, aframe, agenttrail, image-to-3d-pipeline, create-photo-flipbook-ui, meowmeowcatcam, three.js, aetherviz-master
Which topics is it in?augmented-reality, gesture-control, webcam, threejs, webgl, agplv3, 3d, computer-vision, local-first, html, claude-code, ai-agents
Creator
jaredrhod
Size
2.6 MB
Stars
1.1K
Updated
CommitAug 30
Age
2mo
Commits · 90 Days