Skip to main content
This guide walks you through opening Handhold, selecting a course, watching a lesson, and completing your first lab.

​
Prerequisites

Make sure you’ve installed Handhold before continuing.

​
Launch Handhold

open /Applications/Handhold.app
The app opens to the course library.

​
Browse the course library

1

View available courses

The library shows all installed courses. Each card displays the course title, description, and progress.
2

Select a course

Click a course card to open it. If this is your first time, start with an introductory course like “Hash Maps” or “React State Management”.
Handhold ships with a few sample courses. You can download more from the community or create your own using the authoring guide.

​
Watch your first lesson

After selecting a course, you’ll see a list of lessons and labs.
1

Click the first lesson

Lessons are marked with a book icon. Labs are marked with a code icon.
2

Start playback

The lesson opens with a play button. Click it or press Space to start.The narration begins, and visualizations animate in sync with the spoken text.
3

Control playback

  • Space — Play / Pause
  • Left/Right arrows — Jump between narration blocks
  • Escape — Return to course view
4

Watch the visualization

As the narration progresses, code blocks appear on screen. Lines highlight in sync with what’s being explained. Data structures focus on specific nodes. Diagrams trace paths through systems.
Lessons are designed to be watched, not read. Let the narration guide you. The visuals change automatically as the speaker describes them.

​
Complete your first lab

After finishing a lesson, the next item in the course is usually a lab.
1

Click the lab

Labs are interactive coding exercises that reinforce what you learned in the lesson.
2

Read the instructions

The lab opens with a description of what you need to build. Instructions appear in the sidebar.
3

Write code in the editor

The main panel is a Monaco editor (the same engine as VS Code). You can use keyboard shortcuts you’re familiar with.Vim keybindings are available via the settings menu if you prefer.
4

Run tests

Click the “Run Tests” button or press Cmd/Ctrl+Enter.Tests run in a real environment. If the lab requires services like Postgres or Redis, Handhold spins them up in containers automatically.
5

Fix failures and iterate

Test output appears in the terminal panel below the editor. Red means failures, green means passing.Edit your code and re-run tests until everything passes.
6

Mark the lab complete

Once all tests pass, the lab is automatically marked complete. You can move on to the next lesson.

​
Understanding lesson structure

Lessons in Handhold follow a consistent pattern:
1

Problem introduction

The lesson starts by establishing a problem or question. Why does this concept matter?
2

Step-by-step explanation

Each step builds on the previous one. Narration is synchronized with visual changes — when the speaker mentions a variable, that line highlights.
3

Concrete examples

Instead of abstract definitions, lessons walk through real examples. You see code execute, data flow through structures, and systems communicate.

​
Lab structure

Labs are small, focused exercises:
  • 5-20 minutes — Short enough to complete in one session
  • Real code — You write actual TypeScript/JavaScript/Python/etc, not pseudocode
  • Real tests — Tests verify your implementation against edge cases
  • Real services — If the lab needs a database, Handhold spins up Postgres in a container
Labs that require container services need Docker or Podman installed. See the installation guide for setup instructions.

​
Keyboard shortcuts

​
During lessons

KeyAction
SpacePlay / Pause
Left ArrowPrevious narration block
Right ArrowNext narration block
EscapeReturn to course view

​
In the lab editor

KeyAction
Cmd/Ctrl + EnterRun tests
Cmd/Ctrl + SSave (auto-saves on test run)
Cmd/Ctrl + /Toggle comment
Full Monaco editor shortcuts apply (same as VS Code).

​
Course progression

Courses alternate between lessons and labs: 
Lesson 1: Hash functions → Lab 1: Implement a hash function
Lesson 2: Collision handling → Lab 2: Add collision resolution
Lesson 3: Resizing hash maps → Lab 3: Implement dynamic resizing
Each lab builds on previous ones when the content supports it. The final lab often integrates everything you’ve learned.

​
Troubleshooting

Check the console for errors (Cmd/Ctrl+Shift+I opens DevTools). If TTS fails to initialize, the lesson will show an error message.Make sure the app has audio permissions on macOS (System Settings → Privacy & Security → Microphone).
If the lab requires containers and tests fail immediately, verify that Docker or Podman is running:
podman --version
# or
docker --version
Check that the container runtime is on your PATH. On macOS with Docker Desktop, make sure the app is launched.
The Monaco editor can freeze if the window loses focus during initialization. Close the lab and reopen it.If the issue persists, restart Handhold.

​
Next steps

Now that you’ve completed your first lesson and lab:

Explore more courses

Browse the course library and try lessons on different topics

Create your own course

Learn how to write lessons with the authoring DSL and build custom courses

Build docs developers (and LLMs) love

Get started for freeTalk to us