learnlog

A Python package that automatically logs code development and program runs.

By adding import learnlog as the first import in a Python file, every program run is recorded transparently: source code changes, command-line arguments, standard input/output/error, and unhandled exceptions. The data is stored in a hidden local Git repository.

Activating a project

After learnlog init python, activate the project environment in bash:

eval "$(learnlog activate)"
# When finished:
eval "$(learnlog deactivate)"

In Windows PowerShell:

learnlog activate | Invoke-Expression
# When finished:
learnlog deactivate | Invoke-Expression

If PowerShell blocks activation scripts, run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned once for your user. Use --shell bash, --shell powershell, or --shell cmd to choose the syntax explicitly. The commands print code for that shell to execute. Interactive tutorial shell steps need WSL on Windows; learnlog tutorial list works natively.

Use cases

• Sharing live-coding sessions. A teacher adds import learnlog to demonstration scripts during a lecture or tutorial. After the session the teacher pushes the log to a remote repository:

  learnlog set-remote git@gitlab.kth.se:dbosk/lecture01.git
  learnlog push
  

  Students clone the log and replay it step by step:

  learnlog clone git@gitlab.kth.se:dbosk/lecture01.git
  learnlog play
  

  Alternatively, when a shared Git remote is not available, the teacher can export the log as a portable bundle file:

  learnlog export -o lecture01.bundle
  

  The teacher distributes the file (e.g. via a course page) and students replay it directly:

  learnlog play lecture01.bundle
  

  Older recordings can also be reused as debugging case studies for later students.

• Studying, supporting, and reviewing how students code. A researcher creates an empty Git repository for each student. Each student adds import learnlog to their programs and pushes the log:

  learnlog set-remote git@gitlab.kth.se:dbosk/alice-log.git
  learnlog push
  

  The researcher then clones each student's repository to analyse the development data:

  learnlog clone git@gitlab.kth.se:dbosk/alice-log.git
  learnlog play
  learnlog analyse X-Tag=lab1 X-Tag=lab2
  

  The analyse command generates LaTeX reports of edit--run cycles. The optional positional arguments filter events by Column=Regex boundaries—here, only events between tags lab1 and lab2 are included.

  Alternatively, the student can export the log as a bundle and submit it through the course platform:

  learnlog export -o alice-log.bundle
  

  The researcher then replays it directly:

  learnlog play alice-log.bundle
  

  This gives a complete timeline of how students develop and debug their code. Students can use it for self-review, or show a TA what they already tried before asking for help. Teachers can reuse old recordings of authentic problems as debugging instruction material, train TAs on common difficulty patterns and authentic debugging traces, inspect development paths during assessment moderation, improve assignments and curricula, and compare cohorts or interventions. The same recordings also support reproducible bug reports, research on programming process, and authorship review, including possible AI-assisted or externally authored work when the final submission does not match the recorded development path.