CourseForge

Turn messy course files and Git repositories into runnable, step-by-step learning systems with Codex.

中文说明 · Try the 3-minute demo · How it works · Contributing

You saved the course. You cloned the repository. Then you never finished it.

CourseForge adds the missing learning layer: complete source coverage, a clear chapter order, runnable notebooks, beginner-friendly code explanations, reusable modules, and validation—while preserving the original material.

flowchart LR
    A[Scattered scripts<br/>notebooks · docs · data] --> B[CourseForge]
    B --> C[COURSE_MAP<br/>complete coverage]
    B --> D[LEARNING_PATH<br/>ordered chapters]
    B --> E[Notebooks<br/>learn by running]
    B --> F[src + tests<br/>build a real system]

Loading

Try it in 3 minutes

The included demo is offline, deterministic, and requires only Python 3. It shows how three disconnected files become an executable mini-course.

git clone https://github.com/xiaoliu166/courseforge.git
cd courseforge
python3 examples/mini-agent-course/run_demo.py

Expected result:

BEFORE  executable=2 document=1 data=0 other=0
AFTER   executable=4 document=3 data=0 other=0
AGENT   topic=python | sessions=3 | first_step=Read the Python lesson
CHECK   course map, learning path, reusable module, test, and notebook found

Explore the complete Before → After example, then run the repository tests:

python3 -m unittest discover -s tests -v

For a mature real-world repository, read the revisioned, non-vendored Microsoft AI Agents for Beginners case study.

What CourseForge produces

Output	Purpose	Learner benefit
COURSE_MAP.md	Maps every source file to a chapter or explicit exclusion	Know nothing important was silently missed
LEARNING_PATH.md	Defines prerequisites, order, experiments, and completion checks	Always know what to do next
notebooks/	Explains and runs one coherent concept at a time	Learn by observing and changing results
src/	Holds reusable logic extracted from lessons	Finish with a system, not disposable cells
tests/	Verifies important behavior	Distinguish working code from convincing-looking code

Meaningful code explanations

CourseForge uses concise line comments plus a plain-language block summary:

data = load_ohlcv(DATA_FILE)  # Read and normalize daily prices into a date-sorted table
print(f"rows: {len(data)}")   # Count trading records before trusting later calculations
data.head()                   # Inspect columns and values for obvious data problems

# Block summary: Load the market data and perform the first basic sanity checks.

It does not generate low-value comments such as “call the method.” It explains intent, inputs, outputs, assumptions, side effects, and common mistakes.

How it works

1. Inventory code, notebooks, documents, data, dependencies, and Git state.
2. Classify the source as a course folder, existing repository, document collection, or mixed material.
3. Map every executable source to a chapter, appendix, or explicit exclusion.
4. Build the smallest useful learning layer without overwriting the originals.
5. Explain learner-visible code at line and block level.
6. Validate notebooks, Python syntax, tests, source coverage, and Git changes.
7. Extend later chapters through stable src/ interfaces and milestone commits.

Install the Codex skill

git clone https://github.com/xiaoliu166/courseforge.git
mkdir -p ~/.codex/skills
ln -s "$(pwd)/courseforge/skills/build-course-learning-system" ~/.codex/skills/build-course-learning-system

Restart Codex, then invoke the skill explicitly:

Use $build-course-learning-system to turn ./my-course-materials into a
beginner-friendly, executable course. Preserve the originals, inventory every
script, create a course map, and validate all generated notebooks.

Works with more than notebooks

Source shape	Default learning layer
Code-heavy course folder	Ordered notebooks + reusable Python modules + tests
Existing Git repository	Small learning/ layer linked to real application modules
Document-heavy material	Markdown chapters, glossary, exercises; notebooks only when useful
Mixed material	One coverage map across code, documents, data, and media
Quantitative-finance course	Data provenance, adjustment, look-ahead, fee, and evaluation checks

Built-in tools

# Inventory source material without modifying it
python3 skills/build-course-learning-system/scripts/inventory_course.py ./materials

# Audit a partial clone from Git metadata without downloading every file
python3 skills/build-course-learning-system/scripts/inventory_course.py ./repository --git-tree

# Validate a generated learning project
python3 skills/build-course-learning-system/scripts/validate_learning_project.py ./learning-project

# Catch known code-comment semantic mismatches
python3 skills/build-course-learning-system/scripts/check_comment_semantics.py ./learning-project

The tools use the Python standard library and deliberately ignore local environments, vendored dependencies, caches, and notebook checkpoints.

Project structure

courseforge/
├── skills/build-course-learning-system/  # Installable Codex skill
├── examples/mini-agent-course/           # Runnable Before → After example
├── tests/                                # Deterministic script and demo tests
├── CONTRIBUTING.md
└── ROADMAP.md

Contribute a real course shape

The most useful contribution is a small, anonymized directory tree showing material CourseForge does not yet handle well. Open a New course pattern issue—no copyrighted course content or credentials required.

See CONTRIBUTING.md, ROADMAP.md, and PUBLISHING.md for development and release details.

License

MIT © CourseForge contributors