Instrktr

Run hands-on coding courses directly inside VS Code — no browser tab switching, no VMs, no setup friction.

What it does

The Instrktr is a runtime that loads interactive courses into your editor. Each course is a sequence of steps with:

• Instructions rendered as formatted Markdown in the sidebar
• Validators that check your work against the real state of the workspace
• Starter files scaffolded automatically when a step begins
• Hints available on demand
• Open-file links that jump straight to the file you need to edit
• Compare with Solution diff view shown when a check fails or warns
• Step navigation from the panel, command palette, keyboard shortcuts, and status bar

Your progress is saved locally and synced across devices via GitHub Gist (optional, requires sign-in).

Getting started

1. Open the Instrktr panel in the activity bar (the ▶ icon)
2. Start with the bundled JavaScript Fundamentals course, or browse and install another course from the catalog
3. Work through each step in your editor
4. Click Check Work when you think you're done

Installing courses

Click Browse Courses in the Instrktr panel to open the catalog. Install any course with one click — it downloads automatically from GitHub. Installed courses can be started, updated, or removed from the catalog. If git is on your PATH, Instrktr uses git clone for a faster download; otherwise it falls back to a ZIP download.

To run a course you're authoring locally, use the command palette:

Instrktr: Open Local Course Folder

This opens the course in dev watch mode — the panel reloads automatically whenever you save a course file.

Course work files are always created and checked in a learner workspace folder. If VS Code does not already have a folder open, Instrktr prompts you to choose one before starting the course; it will not use extension global storage as the working directory.

Authoring courses

Courses are plain GitHub repos with a course.json manifest and step folders:

course-my-topic/
├── course.json
└── steps/
    ├── 01-first-step/
    │   ├── instructions.md
    │   ├── starter/        ← files copied into workspace on step entry
    │   ├── solution/       ← shown as diff when a check fails (optional)
    │   ├── setup.js        ← runs before the step becomes active (optional)
    │   └── validate.js     ← checks learner's work
    └── 02-second-step/
        └── ...

Instruction panel

Fenced code blocks get syntax highlighting (put a language tag on the opening fence) and a Copy button. Images under the course folder can be referenced with paths relative to course.json; remote https images work too. See the Course Authoring Guide.

Open-file links

In any instructions.md, use open: links to give learners a one-click shortcut to the file they need to edit:

Add the function to [Open `src/index.js`](open:src/index.js).

Solution folders

Add a solution/ folder to a step (mirroring the workspace structure) and reference it in course.json:

{ "solution": "steps/01-first-step/solution" }

When a check fails or warns, a ↕ Compare with Solution button appears. Clicking it opens VS Code's diff editor — learner's file on the left, solution on the right.

Validators — JavaScript or Bash

Write validators in JavaScript or Bash — whichever fits your course:

JavaScript — best for structured checks, JSON parsing, regex, async logic:

// validate.js
module.exports = async function validate(context) {
  if (!await context.files.exists('src/index.js')) {
    return context.fail('Create src/index.js first.');
  }
  const src = await context.files.read('src/index.js');
  if (!src.includes('export default')) {
    return context.warn('File found, but nothing is exported yet.');
  }
  return context.pass('Looks great!');
};

Bash — best for shell-native checks (git, CLI tools, file system). Runs from the course directory so learners can't tamper with it. The workspace is always available as $INSTRKTR_WORKSPACE:

#!/bin/bash
# validate.sh
cd "$INSTRKTR_WORKSPACE" || exit 1

if [ ! -d ".git" ]; then
  echo "No .git directory found. Run: git init"
  exit 1   # fail
fi

COMMITS=$(git log --oneline 2>/dev/null | wc -l | tr -d ' ')
if [ "$COMMITS" -eq 0 ]; then
  echo "Repository created but no commits yet."
  exit 2   # warn — learner can proceed
fi

echo "Git repository ready with ${COMMITS} commit(s)."
exit 0   # pass

See the Validator API reference and Course Authoring Guide for full details and patterns.

Step setup scripts

Steps can include an optional setup script that runs before the step becomes active. Use setup scripts for preparation that should happen on step entry, and validators for checks that run when the learner clicks Check My Work.

{ "setup": "steps/01-first-step/setup.js" }

Scaffold a new course

npx create-instrktr-course

Creates a complete course skeleton with a GitHub Actions release workflow.

Progress sync

Sign in with GitHub (Instrktr: Sign in with GitHub) to sync your progress across machines via a private GitHub Gist. Your data is stored in your own account — the extension never sends it anywhere else.

Configuration

Setting	Description
instrktr.registryUrl	URL to a registry.json file that populates the course catalog
instrktr.startupCourse	Course ID to auto-install and start on VS Code open
instrktr.localCoursePath	Absolute or ${workspaceFolder}-relative path to a local course folder (opens in dev watch mode)
instrktr.presentationMode	Optimize the panel for live presentations by hiding sync controls, hints, solution comparison, and validator checks
instrktr.debugValidatorCommands	Log validator command execution and permission decisions to the Instrktr output channel
instrktr.disableValidatorCommandSecurityChecks	Disable validator command permission prompts for trusted courses
instrktr.webhookUrl	POST learner progress events to an instructor dashboard or compatible webhook endpoint

See the Configuration Reference for full details, scope rules, workshop setup, and monorepo patterns.

Commands

Command	Description
Instrktr: Start Course	Pick from the catalog, a local folder, or installed courses
Instrktr: Browse Courses	Open the course catalog
Instrktr: Open Local Course Folder	Load a local course (dev mode)
Instrktr: Refresh Course Catalog	Force-refresh the registry
Instrktr: Check My Work	Run the active step's validator
Instrktr: Next Step	Move to the next step
Instrktr: Previous Step	Move to the previous step
Instrktr: Jump to Step…	Open a picker for any step in the active course
Instrktr: Restart Course	Reset progress for the active course
Instrktr: Sign in with GitHub	Enable cross-device sync
Instrktr: Sign out of GitHub	Disconnect GitHub account

Keyboard shortcuts

Shortcut	Action
Cmd+Shift+Enter / Ctrl+Shift+Enter	Check my work
Cmd+Shift+] / Ctrl+Shift+]	Next step
Cmd+Shift+[ / Ctrl+Shift+[	Previous step

Instructor dashboard

Set instrktr.webhookUrl to send step pass, failed check, and solution-view events to an instructor dashboard or compatible webhook receiver.

Requirements

• VS Code 1.93 or later
• Node.js is not required — validators run in the extension host
• git is optional — used for faster course downloads when available; falls back to ZIP if not installed

License

MIT