Autodidact

An offline, multi-language interactive learning platform that transforms VS Code into a programming education environment.

Create structured courses with theory lessons and hands-on coding exercises, then let students work through them entirely inside VS Code — no internet connection required.

Features

Sidebar Navigation

Autodidact adds a dedicated sidebar with two panels:

• Lessons — browse and open theory content rendered from Markdown with full syntax highlighting (powered by highlight.js)
  • Lessons are marked as "read" only once you scroll to the bottom
  • Right-click a read lesson → Mark as Unread to reset it
• Exercises — browse exercise folders, open solution files, and run tests directly from the tree
  • After running tests, exercises show ✓ (passed) or ✗ (failed) icons
  • Progress is persisted across VS Code sessions
  • Use Reset Progress (clear-all icon in the title bar) to start fresh

Lesson Webview

Markdown lessons are rendered in a rich webview panel with:

• Syntax-highlighted code blocks for all major languages
• Tables, blockquotes, lists, and all standard Markdown features
• Automatic persistence — reopening VS Code restores the last-viewed lesson

Integrated Test Runner

Exercises use VS Code's native Test Explorer (Testing tab):

• Each exercise has numbered test cases (stdin → expected stdout)
• Tests run against the student's solution and show pass/fail with diff output
• Configurable timeout per test case
• Show Test Diff — open a full side-by-side diff editor comparing expected vs actual output for any failed test case (via the Command Palette)
• Smart error classification — failures are categorised automatically:
  • 🔨 Compilation errors — with the full compiler output
  • ⏱ Timeouts — hints about infinite loops
  • 💀 Crashes — segfaults, stack overflows, division by zero, SIGKILL
  • 🐍🦀🔷🟨⚙️ Language-specific exceptions — Python tracebacks, Rust panics, C# unhandled exceptions, JS/TS errors, C++ terminate messages
  • 🔇 Empty output — reminds to write to stdout
  • ❌ Wrong output — with inline diff and "Show Test Diff" hint

Safety & Sandboxing

Before running student code, Autodidact applies best-effort safety checks:

• Workspace Trust — code execution is blocked in untrusted workspaces
• Suspicious pattern scanning — solution files are scanned for potentially dangerous operations (recursive deletion, shell commands, eval, network access, environment variable exfiltration). Blocking patterns require explicit confirmation; informational patterns are shown as warnings
• Sanitised environment — sensitive environment variables (tokens, secrets, passwords) are stripped before spawning child processes
• Output limits — stdout/stderr are capped at 5 MB to prevent runaway programs from exhausting memory
• Disable pattern scanning via autodidact.enableSafetyChecks in settings

CodeLens

When you open a solution file inside exercises/, three inline buttons appear above your code:

• ▶ Run Tests — run all test cases for the exercise
• 💡 Hints — open the exercise hints
• 👁 Solution — reveal the reference solution

Disable via autodidact.enableCodeLens in settings.

Multi-Language Support

Write solutions in any of six supported languages:

Hints & Reference Solutions

• Progressive Hints — each exercise can include a hints.md file with numbered ## Hint sections. Hints are revealed one at a time via a "Reveal Next Hint" button; progress is remembered across sessions
• Reference solutions — complete working solutions students can reveal after attempting the exercise themselves (shown behind a spoiler confirmation dialog)
• Access via inline icons on exercise folders, editor title bar buttons, CodeLens buttons, right-click context menu, or the command palette

Course Downloader

Use Autodidact: Download Course from GitHub (available from the Command Palette even without an open course) to:

1. Enter a GitHub URL (https://github.com/owner/repo) or shorthand (owner/repo)
2. Choose a download method:
   • Git Clone (default) — clones the repository so it stays connected to the upstream. Every time the course is opened in VS Code the extension automatically runs git pull to fetch the latest lessons and exercises.
   • ZIP Download — downloads a one-time snapshot (no sync)
3. Choose a local folder to save the course into
4. The extension downloads/clones, validates the structure, and offers to open it

Auto-sync: If a course workspace is a git repository, Autodidact runs git pull automatically each time VS Code activates the extension, keeping material and exercises up to date with zero effort.

Course Authoring

Create your own courses by following the structure described in AUTHORING_GUIDE.md. A course is just a folder with:

• A .autodidact marker file (empty, activates the extension)
• A material/ directory with numbered Markdown lessons
• An exercises/ directory with test cases and starter code

Scaffold commands let you quickly add content without manual file creation:

• Create Lesson — adds a new numbered Markdown file in material/ with front-matter template (also available as a button in the Lessons view title bar)
• Create Exercise — creates a full exercise folder with hints.md, test input/output stubs, and language-specific solution files. Prompts for exercise name and target language (also available as a button in the Exercises view title bar)
• Generate Expected Outputs — runs each exercise's reference solution against test inputs and writes the expected output files automatically. Supports generating for a single exercise or all at once, with overwrite confirmation (also available as a button in the Exercises view title bar)

Courses are fully portable — zip and distribute to students who simply open the folder in VS Code.

Getting Started

1. Install the Autodidact extension in VS Code.
2. Open a course folder (one containing a .autodidact file). The included sample-course/ is a complete 11-lesson Rust course you can try immediately.
3. The Autodidact sidebar (mortar board icon) appears automatically with Lessons and Exercises panels.
4. Click a lesson to read the theory in a rendered webview.
5. Click an exercise to open the solution file, then write your code and run tests from the Testing tab.

Sample Course

The repository ships with a sample Rust course aimed at programmers coming from C/C++:

• 11 lessons covering ownership, borrowing, pattern matching, error handling, iterators, traits, lifetimes, and more
• 7 exercises (5 test cases each) with progressive difficulty
• Hints and reference solutions for every exercise

Extension Settings

Commands

All commands are available via the command palette (Ctrl+Shift+P):

Requirements

To run student code, the appropriate toolchain must be installed on the machine:

• Python: python3 (or python on Windows)

• C++: g++ with C++17 support

• Rust: rustc (or cargo for Cargo-based exercises)

• C#: dotnet CLI (.NET 8.0+)

• JavaScript: node (Node.js 18+)

• TypeScript: npx tsx (install tsx globally or as a dev dependency)

• Git: git (required only for cloning courses and auto-sync)

No toolchain is needed just to browse lessons.

Creating Your Own Course

See the Authoring Guide for full documentation on:

• Workspace structure and naming conventions
• Writing lessons in Markdown
• Creating exercises with input/output test cases
• Supporting multiple languages in a single exercise
• Edge cases and best practices

License

MIT