# Vibereps

> Exercise tracker for Claude Code. Setup, test, add exercises, tune detection. Launches pose-detection UI when Claude edits files. Use when this capability is needed.

- Skill: `tomevault-io/vibereps` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/vibereps`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/vibereps/raw
- Safety review: WARNING (external: skill-scanner WARNING, skillspector WARNING)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/vibereps

---


# Vibereps

Exercise tracker for Claude Code. Determine what the user needs based on context:

| User Intent | Action |
|-------------|--------|
| First time / "setup" / "install" | → Setup Flow |
| "test" / "launch" / "run" | → Test Tracker |
| "add exercise" / "custom" / "new exercise" | → Add Exercise |
| "not counting" / "sensitivity" / "threshold" / "tune" | → Tune Detection |
| "pause" / "disable" / "stop" / "break" | → Pause/Resume |
| General question | → Overview |

---

## Overview

Movement breaks while you code. When Claude edits files, vibereps launches a pose-detection exercise UI. Do a few squats or stretches while Claude works, then get notified when it's ready.

**Supported exercises:**
- Standing: squats, jumping_jacks, calf_raises, push_ups, high_knees, standing_crunches, side_stretches, torso_twists, arm_circles
- Seated: shoulder_shrugs, neck_tilts, neck_rotations

All pose detection happens locally via MediaPipe. No video data transmitted.

---

## Setup Flow

### Step 1: Choose Installation Method

Use AskUserQuestion:
```
Question: "How would you like to set up vibereps?"
Header: "Install"
Options:
- "Run installer (Recommended)": "Downloads files, installs menubar app, configures hooks automatically"
- "Manual configuration": "I already have vibereps files, just configure my hooks"
```

**If "Run installer":**
```bash
curl -fsSL https://raw.githubusercontent.com/Flow-Club/vibereps/main/install.sh | bash
```
Then show summary and done.

**If "Manual configuration":** Continue below.

### Step 2: Ask Exercise Mode

```
Question: "What type of exercises would you like?"
Header: "Mode"
Options:
- "Standing & Seated (Recommended)": "Full variety - squats, jumping jacks, plus desk-friendly neck stretches"
- "Standing only": "Active exercises - squats, jumping jacks, push-ups, calf raises"
- "Seated only": "Desk-friendly - shoulder shrugs, neck stretches"
```

### Step 3: Select Exercises

Use AskUserQuestion with MultiSelect: true. Show exercises based on mode:

**Standing:** squats, jumping_jacks, calf_raises, standing_crunches, side_stretches, pushups, high_knees, torso_twists, arm_circles

**Seated:** shoulder_shrugs, neck_tilts, neck_rotations

### Step 4: Find Install Location

```bash
if [[ -f "$HOME/.vibereps/vibereps.py" ]]; then
    echo "$HOME/.vibereps"
else
    echo "$(pwd)"
fi
```

### Step 5: Configure Hooks

Update `~/.claude/settings.json`:

```json
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit|MultiEdit",
      "hooks": [{
        "type": "command",
        "command": "VIBEREPS_EXERCISES={exercises} {vibereps_dir}/vibereps.py",
        "async": true
      }]
    }],
    "Notification": [{
      "matcher": "idle_prompt|permission_prompt",
      "hooks": [{
        "type": "command",
        "command": "{vibereps_dir}/vibereps.py",
        "async": true
      }]
    }]
  }
}
```

Replace `{vibereps_dir}` with full path (not ~) and `{exercises}` with comma-separated list.

### Step 6: Summary

```
Setup complete!

How it works:
1. Claude edits a file → Exercise tracker launches
2. Do a quick exercise while Claude works
3. Get notified when Claude is ready!
```

---

## Test Tracker

**Launch in quick mode** (exercises while Claude works):
```bash
pkill -f "vibereps.py" 2>/dev/null
~/.vibereps/vibereps.py user_prompt_submit '{}'
```

**Launch in normal mode** (after task complete):
```bash
pkill -f "vibereps.py" 2>/dev/null
~/.vibereps/vibereps.py task_complete '{}'
```

**With specific exercises:**
```bash
VIBEREPS_EXERCISES=squats,jumping_jacks ~/.vibereps/vibereps.py user_prompt_submit '{}'
```

**Kill tracker:**
```bash
pkill -f "vibereps.py"
```

**Check if running:**
```bash
lsof -i :8765
```

---

## Add Exercise

### 1. Choose detection type

| Type | Use For | Example |
|------|---------|---------|
| `angle` | Joint angle changes | squats, pushups |
| `height_baseline` | Vertical movement from baseline | calf raises |
| `height_relative` | Position relative to reference | jumping jacks |
| `tilt` | Torso lean | side stretches |
| `distance` | Body parts approaching | standing crunches |
| `width_ratio` | Shoulder/hip width ratio | torso twists |
| `quadrant_tracking` | Circular motion | arm circles |

### 2. MediaPipe Landmark IDs

- Shoulders: 11 (left), 12 (right)
- Elbows: 13 (left), 14 (right)
- Wrists: 15 (left), 16 (right)
- Hips: 23 (left), 24 (right)
- Knees: 25 (left), 26 (right)
- Ankles: 27 (left), 28 (right)

### 3. Create JSON config

Create `exercises/{exercise_name}.json`:

```json
{
  "id": "squats",
  "name": "Squats",
  "description": "Strengthens legs",
  "category": "strength",
  "reps": { "normal": 10, "quick": 5 },
  "detection": {
    "type": "angle",
    "landmarks": {
      "joint": [23, 25, 27],
      "joint_alt": [24, 26, 28]
    },
    "thresholds": { "down": 120, "up": 150 }
  },
  "instructions": {
    "ready": "Squat down below {down}°",
    "down": "Good! Now stand up"
  }
}
```

### 4. Test

```bash
~/.vibereps/vibereps.py user_prompt_submit '{}'
```

---

## Tune Detection

### Common Issues

| Problem | Likely Cause | Fix |
|---------|--------------|-----|
| Not counting reps | Thresholds too strict | Lower `down` threshold or raise `up` threshold |
| Double counting | Thresholds too loose | Tighten thresholds, add hysteresis |
| Counts on wrong motion | Wrong landmarks | Check landmark IDs match exercise |
| Works for some people | Fixed thresholds | Use body-relative thresholds |

### Threshold Locations

**JSON configs** (preferred): `exercises/*.json` → `detection.thresholds`

**Legacy functions** in `exercise_ui.html`:
- `detectLegacySquat`, `detectLegacyPushup`, etc.

### Testing Changes

1. Edit threshold in JSON
2. Restart tracker: `~/.vibereps/vibereps.py user_prompt_submit '{}'`
3. Watch status text for live angle/distance values
4. Adjust based on state transitions

### Both-sides Averaging

For angle-based exercises, use `joint_alt` to average both sides:
```json
"landmarks": {
  "joint": [23, 25, 27],
  "joint_alt": [24, 26, 28]
}
```

---

## Pause/Resume

Temporarily disable vibereps until a specified time.

### Pause Until End of Day (default)

```bash
~/.vibereps/vibereps.py --pause
```

### Pause Until Specific Time

```bash
# ISO format timestamp
~/.vibereps/vibereps.py --pause "2026-01-30T18:00:00"
```

### Resume

```bash
~/.vibereps/vibereps.py --resume
```

### Check Status

```bash
~/.vibereps/vibereps.py --status
```

### Via Menubar

If using the VibeReps menubar app, click the tray icon and select:
- **"Pause Until End of Day"** to pause
- **"Resume VibeReps"** to resume (shown when paused)

### Via HTTP API (Electron app)

```bash
# Check pause status
curl http://localhost:8800/api/pause

# Pause until end of day
curl -X POST http://localhost:8800/api/pause

# Pause until specific time
curl -X POST http://localhost:8800/api/pause \
  -H "Content-Type: application/json" \
  -d '{"until": "2026-01-30T18:00:00"}'

# Resume
curl -X POST http://localhost:8800/api/resume
```

---

## Links

- [GitHub](https://github.com/Flow-Club/vibereps)
- [Documentation](https://github.com/Flow-Club/vibereps/tree/main/docs)

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/flow-club) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->