Handhold is a desktop app for interactive programming courses. Each lesson is a narrated walkthrough where code, diagrams, and data structures animate in sync with spoken audio. Labs give you a real editor, real tests, and real services to build against.

One command. Detects your OS, checks dependencies, downloads the latest release, and installs it.

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/dutch-casa/handhold/main/scripts/install-handhold.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/dutch-casa/handhold/main/scripts/install-handhold.ps1 | iex

The installer prompts to set up optional dependencies (Docker or Podman for labs) and handles platform quirks like macOS Gatekeeper for unsigned apps. Lessons never require containers -- only labs that spin up services like Postgres or Redis.

Everything below is for contributors building Handhold from source.

Built with Tauri 2 and React 19.

macOS -- Xcode Command Line Tools:

xcode-select --install

Linux (Debian/Ubuntu):

sudo apt-get install -y \
  libwebkit2gtk-4.1-dev \
  libappindicator3-dev \
  librsvg2-dev \
  patchelf \
  build-essential \
  curl \
  wget \
  file \
  libssl-dev \
  libgtk-3-dev

Other distros: see Tauri Linux prerequisites.

Windows -- WebView2 (ships with Windows 11, manual install on Windows 10) and Visual Studio C++ Build Tools.

The installer has a --dev flag that checks for Rust, Bun, Tauri CLI, and platform build deps:

git clone https://github.com/dutch-casa/handhold.git
cd handhold
bash scripts/install-handhold.sh --dev

Or use the standalone dev setup script (if you've already installed deps manually):

bash scripts/install.sh

Both scripts check prerequisites, install frontend packages, download the TTS sidecar binary, and verify the Rust build.

Handhold uses Kokoro for text-to-speech. The koko binary must be built separately and placed in src-tauri/binaries/koko-<target-triple>. The install script tells you if it's missing.

bun tauri dev

Opens the app with hot reload. Frontend changes apply instantly; Rust changes trigger a recompile.

bun tauri build

Outputs a platform-native installer (.dmg, .AppImage/.deb, or .msi).

handhold/
  src/                     React frontend
    types/                   IR types (lesson, course, lab)
    parser/                  Markdown -> typed IR
    code/                    Code primitive (Shiki + diff + animated lines)
    data/                    Data structure primitive (layout + SVG)
    diagram/                 Diagram primitive (topo-sort layout + SVG)
    preview/                 Live HTML/React preview (iframe)
    tts/                     TTS bridge (synthesize, audio player)
    presentation/            Playback engine (store, triggers, components)
  src-tauri/               Rust backend
    src/
      lib.rs                 App setup, menus, invoke handlers
      tts.rs                 Kokoro TTS backend
      container.rs           Podman/Docker orchestration for labs
      pty.rs                 Terminal emulation
      lsp.rs                 Language server protocol bridge
      db.rs                  SQLite persistence
  docs/                    Authoring guide
  scripts/                 Build and setup scripts
  .claude/skills/          Course authoring skill (for AI-assisted course creation)

Courses are markdown files with an embedded DSL for triggers, animations, and visualization blocks. The full reference lives in two places:

• docs/authoring-guide.md -- quick-start guide
• .claude/skills/handhold-course-authoring/ -- comprehensive skill for AI-assisted authoring

Push a version tag to trigger a cross-platform release build:

git tag v0.1.0
git push origin v0.1.0

Builds .dmg (macOS ARM + Intel), .AppImage + .deb (Linux), and .msi + .exe (Windows). Artifacts upload as a draft GitHub Release.

AGPL-3.0

Copyright 2026 Dutch Casadaban.