entrain

A kinesthetic AI partner. You move; it moves back.

Not to grade you. Not to teach you. To play with you — build motifs together, develop a private vocabulary, and eventually attune to your nervous system the way a great comedian's timing or a teacher's voice does.

Working name. The project is "an embodied agent that co-regulates through movement (and later, voice and breath)." See VISION.md.

Status

Phase 1.1 in progress (2026-05-12). Pose pipeline live — webcam → MediaPipe Pose → keypoint overlay + derived features. No character or AI yet; this is the substrate.

• VISION.md — the bigger story (co-regulation, consciousness modulation, lineage)
• docs/architecture.md — two-tier loop, perception / expression, motif memory
• prompts/base-prompt-v1.md — the base prompt for the agent
• docs/brainstorm-session-1.md — full design archaeology
• docs/open-questions.md — design forks not yet decided

Tracking work in beads — bd ready to see what's next.

Run

./serve.py
# → http://localhost:8731 (auto-increments if 8731 is taken)

Then open the URL in Chrome / Safari / any modern browser, click Start camera, grant permission, and move around. You should see:

• A doodled partner figure in the middle of the screen, mirroring your pose 1:1
• Yourself in a small webcam pip (bottom-left) with skeleton overlay
• Five derived features (motion / openness / symmetry / verticality / focal limb) in the panel (top-right)
• ~30fps on a recent Mac

Browser-side errors / warnings / info posts to /api/frontend-log and stream in the terminal as [FE-ERROR], [FE-WARN], [FE-INFO] lines.

Everything runs locally. No data leaves the browser.

Test harness

The pose-feature math is pure JS (no DOM, no MediaPipe), exported from src/features.mjs. Test it headlessly:

node tests/run-features.mjs                            # runs against synthetic wave fixture
node tests/run-features.mjs path/to/trace.json         # against your own recorded trace
node tests/make-fixture.mjs > tests/fixtures/foo.json  # regenerate the synthetic fixture

Record your own trace from the browser: click ● record 5s trace in the bottom-right. A trace-YYYY-MM-DD….json file downloads to your Downloads folder. Load it back via load trace… to replay without a camera (useful for debugging partner rendering against the same motion repeatedly).

Ancestry

• github.com/tmad4000/Dancebot (Mar 2026) — abstract gestural companion, knob-driven visuals. Different concept (response-as-vibe rather than response-as-partner), but the camera + pose plumbing is reusable.

Cousin projects

• Tone-of-voice modulation (sibling) — same co-regulation premise applied to spoken prosody. Should eventually share a "user nervous-system model" with entrain.
• Desktop companions Kitsune & Nymeria (openclaw-kitsune) — animated creatures with personality. Could become entrain's embodiment when the substrate's ready.