barehands: a webcam hand-tracked board for your AI

What barehands actually solves, and for whom

The problem is not hand tracking. MediaPipe already does that, and the repository credits Google MediaPipe under Apache 2.0 for the tracking and three.js under MIT for the rendering. The problem barehands addresses is the gap between an AI that produces text and a person who wants to see the thing being discussed. The README frames the board as a stage and the on-screen ring as a face: the ring reads tiny files in state/, so writing thinking, idle, listening or speaking to state/state makes it react, and bin/board.sh sends a card to center stage. That makes the target user someone already running an agent loop, most visibly Claude Code users, who can hand the repository to their agent and say "read barehands.md and set me up." It is a poor fit for anyone who wants a finished consumer application. There is no installer binary, no release artifact, and the README's own run instructions are three shell lines.

How the tracker, the stage page and the file protocols fit together

The architecture is deliberately split so that no component needs privileged access. server.py is stdlib Python and serves the page; the browser does the tracking. The tracker page owns the camera, and stage.html?role=render is described as a transparent mirror of it, built for an OBS browser source so the glass composites over your camera feed with real alpha. Hand tracking and 3D both load from public CDNs on first run, and the repository redistributes neither library.

The AI side is files and localhost HTTP, not a socket protocol. Inbound, the ring polls state/state for a single word. Outbound, bin/board.sh posts a JSON action, and bin/board-state.sh prints what is currently on the board so an agent can look before it talks. The README lists present, add_card, add_img, hand, explode, yank and hover as the staged verbs, and states that the server enforces an action allowlist and the media jail. That allowlist is the interesting design decision: it means you can hand the board to an assistant without giving it arbitrary filesystem reach, at the cost of the assistant being unable to do anything the allowlist does not name.

Installing barehands and getting a first card on the board

The README gives a three-line install with no dependency step, because the server is stdlib Python and the front end pulls its libraries from CDNs. Clone and start it:

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

On Windows the README says to run run.bat instead, and explains why: 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. After the server starts, open the stage page in Chrome and allow the camera:

# open in Chrome
http://127.0.0.1:8794/stage.html

You should see the board over your camera feed. Tap the ring, tap an orb, and the sample notes unfold; the README says those notes teach the gestures from inside the board itself, under Getting Started then The Gestures.

Pointing an orb at your own notes is a config edit, not a UI flow. The repository ships barehands.json.example, and the README shows the shape:

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

One line per orb. A folder of .md files works, and the README states an Obsidian vault works as-is. Finally, the agent-facing call, which is what most readers will actually wire up:

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

If that returns cleanly, the allowlist accepted the action and the card should fly center stage, enlarged and spotlit with everything else dimmed.

The media jail is the best decision in the repository

Only files inside media/ can ever appear on the board, and the README calls that jail a safety feature. It is right to. The board is designed to be driven by an AI, and an AI driving a renderer that can pull any path on disk is an exfiltration surface. Constraining the visible file set to one directory means the worst an over-eager agent can stage is something you already put in media/misc/, media/fx/, media/models/ or media/holo/. The holo folder is a rendering choice rather than a separate asset type: the same model renders as a blue hologram wireframe.

The trade-off is real. If you want to present a document from your vault as a card, you either copy it into media/ or rely on the notes orb path, which is a separate kind from media. Two mechanisms for getting content on screen means two mental models, and the README does not explain how a notes orb renders a file compared with a media orb. That is a gap, not a bug.

Gesture tuning, and where the documentation goes quiet

The gesture set is larger than a demo: tap opens and closes, pinch-drag moves, holding still while carrying rotates in 3D, two hands scale, a flick throws, a clap sweeps the board clean. The claw is the memorable one, and it is a deliberate sequence rather than a pose: flash your hand open, claw, aim across the screen, let it strain and shake for two seconds, then snap shut. An empty pinch dragged sideways scrubs a 3D model's exploded view.

The README claims every threshold was tuned on a real hand across weeks of live use, and that because the gates measure hand shape as ratios rather than size, they hold at any camera distance. That is a plausible mechanism, and it is the reason the project ships TROUBLESHOOTING.md with a debug overlay and pose sampler. But a two-second strain-and-shake trigger is a timing gate, and timing gates are exactly what a threshold tuned on one person's hand will get wrong for another. The README acknowledges this by pointing at the tuning clinic rather than promising universal accuracy.

What the documentation does not cover is failure recovery. There is no documented way to reset the tracker if the camera is grabbed by another application, no stated behaviour when the CDN is unreachable on first run, and no rollback procedure if an update regresses your gestures. The README does not document rollback. The update section says gesture fixes ship often, which cuts both ways: fixes arrive, and so do regressions.

Streaming output and the OBS path

The streaming section is the most concretely specified part of the README, and it is where the two-page split earns its keep. stage.html?role=render is a transparent mirror, so an OBS browser source composites the glass over OBS's own broadcast camera with real alpha. Query parameters tune it: &cursors=0 hides the finger rings, &ss=2 renders at 2x for sharper cards, ?portrait=1 on the tracker flips the rig to vertical 9:16 for Shorts and TikTok, and ?res=3840x2160 bumps the tracker's capture for a 4K self-view, with 1280x720 named as the rescue for slow machines. In an OBS rig the broadcast camera is OBS's own source, so the README says tracking can stay at the default resolution.

That last note is the useful one. It tells you the tracker resolution and the broadcast resolution are independent concerns, which is not obvious from a single-page tool. If you are not streaming, this whole section is dead weight, and the transparent-mirror design is the main reason the project needs two pages instead of one.

Updating, licensing and what you are taking on

Updates are shell scripts, not a package manager. On macOS the README says setup leaves an Update icon on the Desktop, or you run ./update.sh in the folder. On Windows, or any time, you ask your agent to pull the latest and tell you what changed. If you installed through fullstack-agent, ./fullstack-agent/update.sh updates every piece at once. The repository also ships update.bat. The stated guarantee is that your config, your notes and your media stay untouched because they live outside the tracked files, which matches the layout: barehands.json, media/ and state/ are separate from the tracked source. Note that the README does not version this: there is no changelog file in the top-level entries and no releases were retrieved, so "tell me what changed" depends on your agent reading the diff.

The licence is AGPL-3.0. The README describes it as 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 licence. The network clause is the part that catches people: if you run a modified barehands as a service others interact with, AGPL-3.0 obligations attach to that service, not just to distributed binaries. If your plan is an internal tool on your own laptop, this is unlikely to matter. If your plan is a hosted product, read LICENSE with your own counsel. Nothing here is legal advice.

The maintenance picture is simple: the repository is not archived, and the last push was on 2026-08-30.

Alternatives and the honest comparison

The nearest thing in the same space is a headset or controller pipeline, and the difference is not quality, it is what you are buying. A headset gives you tracked controllers with buttons and a known coordinate frame; barehands gives you a webcam, an empty room requirement, and a set of gesture gates tuned on one hand. If you need reliable input for long sessions, the headset wins on determinism. If you need zero hardware and a surface your agent can write to, barehands is the smaller commitment.

The other comparison is against building it yourself. MediaPipe is Apache 2.0 and three.js is MIT, both public, and a competent front-end developer could assemble a hand-tracked card renderer. What barehands adds on top of that stack is the boring part that takes the time: the action allowlist, the media jail, the state file the ring polls, the two-page tracker and render split for OBS, and the gesture thresholds. That is the actual product. If your needs are a single demo, the libraries alone are enough. If your needs are an agent that stages things on a board all day, the allowlist and the jail are why you would take this repository rather than start from the MediaPipe samples.

Editorial conclusion

Adopt barehands if you want a gesture surface your own agent can drive, you are comfortable editing barehands.json by hand, and you accept that the board is a localhost page rather than a packaged app. Skip it if you need a supported product, a headset-grade tracking guarantee, or a stable interface contract, because the README states gesture fixes ship often and the protocols are described in prose rather than versioned schemas. Verify three things first: that python3 server.py starts and 127.0.0.1:8794/stage.html loads in Chrome with camera permission, that your vault path appears as an orb after you edit barehands.json, and that bin/board.sh returns without an allowlist rejection on your machine. Nothing else in the repository tells you those three will work on your hardware.

Frequently asked questions

Official sources

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