barehands: A Webcam-Powered Hand-Tracked Interface for Your AI

What barehands Is and Who It Serves

barehands answers a specific question: what if your AI session had a physical surface you could reach into? The project turns a webcam and Chrome into a spatial board where files appear as glass cards, 3D models float in the camera view, and pinch gestures move, throw, and scale everything. There is no headset, no controller, and no glove. The camera feed stays on screen; the glass cards composite over it.

The README describes two kinds of users: someone who wants to interact with files and notes during an AI session, and a developer who wants to wire an AI agent into a visual display. Any program that writes a small file or sends an HTTP request to localhost can act as the brain. The on-screen ring is the agent's face. When your AI writes "thinking" to state/state, the ring reacts; when it calls bin/board.sh with a JSON payload, content flies onto the board.

Getting barehands Running

The install is three commands on macOS and Linux:

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

On Windows, the README recommends run.bat instead of python3 server.py. Windows 11 ships a Python Store stub on the PATH that looks like an interpreter but is not one, and run.bat finds a working interpreter instead.

Once the server is running, open http://127.0.0.1:8794/stage.html in Chrome and allow camera access. The README states the server is stdlib Python with no external dependencies: Google MediaPipe for hand tracking and three.js for 3D rendering both load from CDNs on first run, so the repository itself ships no compiled code. The sample notes on the board walk through the gesture set from inside the interface.

For users already inside a Claude Code session, the README offers an alternative: tell the agent to clone the repository and read barehands/barehands.md. The README states the agent installs, configures, and wires itself in from that one instruction.

Configuring Vaults and Media Orbs

The board's content comes from orbs defined in barehands.json. Each orb points to a folder on disk. Notes orbs read markdown files; media orbs load images, 3D models, and other assets.

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

The README states that an Obsidian vault works as-is because the vault is a folder of markdown files. The media orb has a defined structure: images in media/misc/, transparent props in media/fx/, 3D models in media/models/, and hologram wireframe models in media/holo/. The README describes this as a safety feature: only files inside media/ can appear on the board. Files outside that folder cannot be pulled onto the stage.

Wiring in an AI Agent

barehands communicates with an AI through two small protocols the README calls "dead-simple." The ring reads a text file: write a single word such as "thinking", "idle", "listening", or "speaking" to state/state and the ring animates accordingly. No file, no problem; the ring idles on its own.

The board accepts JSON commands via bin/board.sh. The README gives this example for showing content on the main stage:

bin/board.sh '{"a":"present","title":"THE PLAN","body":"..."}'

The present action brings content center stage, enlarged and spotlit, with everything else dimmed. Other verbs listed in the README include add_card, add_img, hand, explode, yank, and hover. The server enforces an action allowlist and the media jail, so the README describes it as safe to hand to an AI assistant.

bin/board-state.sh prints the current state of the board so your agent can observe what is already on screen before acting. Claude Code users can wire the ring to their sessions by adding two hooks in settings.json; the README states the setup wizard pastes them automatically.

The README also notes that anything capable of writing a file or curling localhost can act as the brain: a local LLM, a cron job, or a Stream Deck button. The protocol is intentionally minimal so non-Claude agents can integrate without special support.

The Gesture Set and How Detection Works

The README describes each gesture precisely. Tap (a quick pinch) opens and closes cards. Pinch-drag moves a card. Holding still while carrying rotates it in 3D. Two hands simultaneously scale. A flick throws a card. Clapping, defined as palms together with fingers up, sweeps the board clean. The claw is the most complex gesture: open your hand, form a claw, aim at something across the screen, hold for two seconds while the gesture strains, then snap the claw shut to pull the target to your hand.

The README explains that gesture thresholds are calibrated using hand shape as ratios rather than absolute distances, so the detection holds regardless of how far from the camera your hand sits. If a gesture misfires, TROUBLESHOOTING.md ships a tuning clinic with a debug overlay and a pose sampler. The README describes the exact method for having your AI agent fit the thresholds to your hand.

Streaming and Recording Support

barehands supports OBS-based recording through a second page. The tracker page owns the camera. Adding ?role=render to stage.html creates a transparent mirror of the tracker suitable for an OBS browser source. The glass composites over the camera feed with real alpha.

The README lists several URL parameters for tuning the render page. The parameter &cursors=0 hides the finger rings for a "bare-hands sorcery" effect in recordings. The parameter &ss=2 renders at twice resolution for sharper cards. The parameter ?portrait=1 flips the rig to vertical 9:16 format for short-form video. The parameter ?res=3840x2160 raises the capture resolution for a 4K self-view, while 1280x720 rescues slow machines. In an OBS rig the README notes that the broadcast camera is OBS's own source, so the tracker can stay at its default resolution.

Limitations and AGPL-3.0 Licensing

barehands has no packaged installer and no release artifacts on GitHub. Every install starts with a git clone. The server requires Python 3 but the README does not state a minimum version. Windows users must avoid the built-in Python stub on PATH and use run.bat instead.

Hand tracking relies on Google MediaPipe loaded from a CDN, so first-run setup requires an internet connection. The README does not document offline operation.

Updates are not automatic. On macOS the README describes a desktop icon created by the setup wizard, or users can run ./update.sh. On Windows or via an agent, the README suggests telling your agent to pull the latest barehands.

The project is licensed under AGPL-3.0. The README states it is free to use, modify, and build on, including commercially inside your own business. The share-alike requirement activates when you distribute a modified version to users: that version must be released under the same AGPL-3.0 terms. Internal business use without distribution does not trigger the copyleft clause.

Editorial conclusion

barehands suits engineers and hobbyists who want a spatial board for their AI sessions and are comfortable running a local server and configuring JSON files. It is a poor fit for teams needing a turnkey product: file paths, SSH wiring, and AGPL compliance all require hands-on setup. Before deploying it inside a business, review the AGPL-3.0 terms, which require publishing source code for any modified version distributed to users, and confirm that the Claude Code session hooks in settings.json match your actual workflow.

Frequently asked questions

Official sources

1. Issues
2. jaredrhod/barehands on GitHub
3. License: AGPL-3.0
4. Project website
5. README