VCR (VS Code Recorder)

VCR is an early student IDE session-recorder prototype.

After installation, select the VCR icon in the Activity Bar to open the Student Recorder panel. Paste an instructor-provided Git repository URL to add a course. Installed course cards can be synced on demand or removed; removing a course does not remove student workspace files. New courses default to courses in the home folder, and students can change that code folder. Moved course folders can be re-linked with Locate folder.

Open reuses the current window when no folder is open. If the course is already a folder in the current workspace, it shows Explorer. Otherwise, it opens a new window to preserve the folders already open.

Select Change code folder and enter an absolute path (such as D:\School\Code on Windows or /mnt/school/code on macOS/Linux), or a path relative to your home folder (such as School/code). VCR creates that folder if needed and places new course folders directly inside it. Existing courses stay where they are, and saved folder settings survive upgrades and restarts.

A vcr-recording.json in an opened folder lists recording scopes:

{"version": 1, "trackedFolders": ["exercises/*", "assignments/*", "projects/final"]}

Paths use / and are relative to the configuration file's directory. Listed folders and their descendants are recorded without needing their own config. Folder patterns use glob syntax (not regular expressions), with / separators:

* matches zero or more characters within one folder name; ? matches one. ** as a whole segment matches zero or more directory levels. Character classes support ranges and negation ([!0-9]); braces support alternatives and ranges (assignment-{01..12}). Patterns may be nested to any depth. Newly created matching folders are recorded without config edits or reloading. Each matched folder is a separate scope; for assignments/**, every descendant folder becomes a scope, and the deepest match wins. Use assignments/* when you want one scope per assignment, including all of its descendants.

Matches include hidden folders but exclude files, symbolic links/junctions, .git, .vcr, and vcr-sessions at every depth. Patterns are relative to the config directory and case-insensitive on Windows. Unmatched patterns select no folders. Literal paths remain supported and overlapping matches are deduplicated. Negated patterns (!path), extglobs (@(a|b)), backslash escapes, absolute paths, and .. traversal are unsupported. Patterns are limited to 4096 characters and 1024 brace alternatives; unsafe brace alternatives are rejected too.

The closest ancestor config applies; within it, the deepest matching listed folder wins. A closer empty config excludes its subtree from ancestor capture. Configuration creation, edits, and deletion refresh routing; existing recordings are preserved. Invalid configs fail visibly and require fixing and reloading.

Git repositories store captures only in <recording-worktree>/<folder>/vcr-sessions/, on vcr-recordings. Enrolled Git courses retain root capture for activity outside their root config's listed folders, including when the root config is missing or empty. A config-only Git repository records listed folders without course enrollment; course-management and submission-push commands still require an enrolled course.

Non-Git folders need neither Git nor vcr-course.json. Each listed folder stores captures in its own .vcr/vcr-sessions/. .vcr is hidden by default in VS Code Explorer, has the Windows hidden attribute, and uses a dot-prefixed name on macOS/Linux. Users can override Explorer hiding. Unlisted activity is excluded. Git repositories never fall back to local .vcr storage if Git is unavailable. Converting a course between Git and non-Git modes is not a supported migration.

Configuration discovery is limited to opened workspace folders and excludes .git, .vcr, and node_modules. Linked paths are rejected. Capture always excludes .git, .vcr, and vcr-sessions. Existing user-wide captures remain preserved. This records observed editor sessions and filesystem create/delete notifications; it does not reconstruct every external disk edit or activity while VS Code is closed.

Every configured folder offers Create ZIP in the Recorded folders panel. The VCR: Create Recorded Folder ZIP palette command and Explorer folder context menu provide the same action. These package saved source files and recordings into ~/vcr-submissions; course-card ZIPs also allow source-file selection. Recordings are always included under .vcr/vcr-sessions/ in the archive, including nested recorded folders. Git ZIPs read captures from the worktree; non-Git ZIPs include the local .vcr directories. This window's pending captures are flushed; other windows contribute complete records already on disk. Unsaved editor text is preserved in recordings without saving source files. Uploads remain manual. External ZIP tools may omit hidden files.

For Git repositories, VCR automatically saves recording-only local Git commits every 60 seconds while active, at startup, and on normal shutdown, with no prompts or success popups. These use the vcr-recordings branch and the VCR Recorder identity. A dedicated worktree inside Git's private directory (.git/vcr-recordings-worktree for a normal checkout) holds Git captures. View history with git log vcr-recordings or locate the directory with git worktree list. Your current branch, staged changes, source files, and VS Code configuration are untouched. Capture files do not clutter the source checkout's git status or git add .. There is no automatic push. If a commit fails, recordings remain on disk and VCR retries; a status-bar warning points to the VCR recording commits Output channel. After a crash, startup saves complete journal records from all recording-worktree scopes; an incomplete trailing record stays on disk. Normal shutdown attempts a final save, but abrupt termination cannot.

Push a submission

Connect your own repository once, from the course checkout:

git remote add origin https://github.com/STUDENT/COURSE-REPO.git

Commit source changes as usual:

git add .
git commit -m "Complete assignment"

Then click Push submission on the course card, or select VCR: Push submission from the Command Palette. Choose a course if more than one is available. VCR flushes this window's pending captures, commits them, and pushes both the current code branch and vcr-recordings to your origin atomically. It does not save unsaved source buffers or commit staged/unstaged source changes. New events arriving during the push belong to the next submission.

When submitting from different computers, VCR fetches and combines their recordings automatically, preserving both histories and attempt identities. This combination happens only in the submitted commit; local recording files stay in their own worktree. Incompatible versions of the same journal block submission and require resolution. A remote update during submission can still reject the push; retry to include the latest recordings.

A plain git push of your code branch does not send the recording branch. git push --atomic origin HEAD vcr-recordings sends both already committed branches but does not flush pending captures or combine remote recordings. Use the VCR action for that. The instructor can inspect both branches in your student repository.

Configure Git authentication normally. Missing origin, an origin matching the instructor repository, detached HEAD, authentication failures, divergent remote code history, conflicting recordings, or lack of server atomic-push support produce an error. VCR never force-pushes or retries as a partial push. Resolve remote/history issues using Git, then retry. Switching source branches does not switch or remove captures; the recording worktree stays on vcr-recordings. Earlier development captures are not migrated or deleted.

Each capture directory contains attempt.json and append-only .jsonl segments. Restarts and concurrent windows use separate files. Existing recordings are preserved. Invalid or mismatched attempt identities report an error rather than being replaced. Do not distribute generated recordings in starter repos.

Capture includes opened editor text, edits (including unsaved changes), saves, and closes. Selection and focus changes are not recorded. Journals and .git directories are excluded. Unopened files, binary files, untitled buffers, and arbitrary commands are not captured. Disable VCR to stop recording and reload if prompted. Playback is available in the separate Replay extension (impleta.replay). Tamper protection, attempt finalization, and reset are not implemented.

The instructor repository is stored as the upstream Git remote. Students can save local checkpoints, sync instructor updates, review configured folder files, and create ZIPs under vcr-submissions for manual upload. VCR does not upload or claim delivery of those ZIPs.

Course repositories require a root vcr-course.json manifest; no assignment or exercise folder names are required. The complete manifest format is documented in the repository's root README, including the languages array of course language IDs.

Instructors can commit cross-platform .vscode/tasks.json and .vscode/launch.json files when a course needs F5 build or launch behavior. VCR clones and syncs those tracked files normally and preserves them when a course is removed or its checkout is re-added. VCR does not generate workspace configuration.

Sync instructor updates updates files changed only by the instructor. Your committed, staged, and unstaged changes are preserved; unrelated edits and recordings do not require a checkpoint first. Unsaved editors in this window, untracked files, and ignored files also protect colliding paths. If both sides changed a file, VCR keeps your version and lists the pending path in the panel while applying independent updates. Renames and directory/file replacements are kept together. Skipped paths remain pending after restart and are checked again on the next sync. Linked/submodule updates are conservatively skipped.

VCR does not restore files, insert conflict markers, or offer a restore action. Use Git yourself to resolve overlaps or restore accidental edits, including the index and committed version where needed, then sync again. A sync may create a local integration commit without committing your staged or unstaged work. Finish existing merges/rebases/cherry-picks before syncing. Rewritten instructor history and invalid course metadata stop sync safely. Sync never pushes.

VCR can be disabled, re-enabled, and uninstalled through VS Code's normal Extensions view.

Git must be installed and available on PATH to add or sync courses. VCR checks for Git when the extension activates and displays installation guidance when it is missing.

VCR does not install or manage compilers, runtimes, debuggers, or language extensions. Students install required language support separately. Removing a course never deletes VS Code configuration or student files.

Debugging

Open the repository root (the folder containing this extension's parent package.json) with File > Open Folder..., press F5, and select Run VCR Extension if prompted. A separate Extension Development Host window opens with VCR loaded.

Associating another checkout

With VCR enabled, opening a qualifying repository automatically adds it to VCR and starts course-scoped recording without an acceptance prompt. Disable the VCR extension to stop recording. Discovery checks workspace folders and open file editors, including on startup and when workspace folders are added.

A qualifying repository has a valid root vcr-course.json, valid optional vcr-recording.json, a checked-out branch with a commit, and an upstream remote exactly matching the manifest's remoteUrl. An origin remote alone does not qualify for automatic enrollment. Linked paths and manifests below the Git root are rejected. Discovery does not clone, move files, rename remotes, or upload anything. An alternate checkout of an existing course switches its enrolled path; the previous checkout's files and recordings remain on disk. Removing a course preserves its checkout; opening it again can rediscover it. Leaving a course does not emit navigation events or record the outside destination. Old user-wide captures remain available for manual review; VCR does not submit them.

Compact recording format

New JSONL segments use format version 1. Session IDs (attemptId, segmentId, sourceWindowId) appear only in the header and apply to every record in that file. The compact format is the initial recording format; prerelease formats are unsupported.

The first observation of each document stores its full buffer, including unsaved text. Edits normally store version and changes, each containing UTF-16 offset, replacement length, and inserted text. Apply changes in recorded order (descending offset) to the previous buffer, whose version must equal the edit version minus one. Unchanged save and close events omit text. Selection, cursor, focus, and scope-visit events are not recorded.

Any event with snapshot: true and text replaces the reconstructed buffer. Snapshots occur on opening/reopening, every 100 continuous edits, and whenever versions or changes cannot safely reproduce the current buffer. Each segment is independently reconstructable. The first event for each document defines its numeric doc ID and path; later events use only doc. Unchanged metadata events inherit the document version; null edit reasons are omitted. seq orders events. Event timestamps are header startedAt plus ms, which can be negative for observations queued before the header was created. Read-only playback is available in the separate Replay extension.

Copy/paste provenance

Only actual document edits carry paste observations; copy and paste requests do not create journal events. A matching edit may include paste with correlation: "candidate" and origin: "same-file", "course-file", or "unknown". Known origins include a course-root-relative sourcePath, sourceVersion, UTF-16 offset/length sourceRanges, and evidence: "window-copy-metadata". operation is "cut-inferred" when the next source revision deletes every copied range, otherwise "copy-or-cut". This is evidence, not proof of the cut command: copy followed by deletion can look identical. Undo/redo are never inferred cuts.

VCR attaches an opaque, window-local token through VS Code's copy/paste provider. The latest source metadata and a text hash stay in memory; neither the token nor the hash is journaled. It reads text from the operation's data transfer only for eligible course files, never polls the system clipboard, and never supplies paste edits or changes plain text. Out-of-course source paths/content are not recorded. Unknown origin includes external applications, other windows, prior sessions, other courses, replaced tokens, and missing metadata; it does not prove external origin.

Correlation requires the next document version and matching replacement ranges within two seconds. Cancellation, undo/redo, overlapping requests, closing, and focus changes prevent correlation. Identical unrelated edits can still match. Exact document changes are authoritative. Provider bypasses, Paste As options, formatting, and other extensions may leave an edit unclassified. UI coverage must be checked using the manual test matrix. Read-only playback is available in the separate Replay extension.

Terminal and Run/Debug recording

VCR records shell-integration command lines (terminal.start / terminal.end), raw output chunks including ANSI sequences (terminal.output), and reported exit codes. An output stream failure produces terminal.outputError. Execution and terminal IDs correlate concurrent commands; output can arrive after the end event. Commands are scoped by the local working directory reported at command start, including exact configured folders. Unknown, remote, or outside-course working directories are skipped; editor focus never supplies a terminal's scope.

Task lifecycle records (task.start, task.processStart, task.processEnd, task.end) include build task names and available process/exit codes. Debug lifecycle records (debug.start, debug.end) include the session name, debugger type, and noDebug flag. These observe sessions launched using F5, Ctrl+F5, or menus. Tasks and debug sessions use their explicit workspace folder, normally capturing at the course root. Global tasks and sessions without a workspace folder are skipped. Failed launches before a session starts have no debug record.

Debug-adapter stdout, stderr, console, and important output events are recorded as terminal.output with the debug session execution ID and source: debugAdapter. Telemetry and structured adapter payloads are excluded. Output can precede the session start event. Output routed directly to a terminal still requires an observable shell execution; external consoles are not captured.

This is not a keystroke log: unsubmitted shell edits, hidden input, prompts outside command execution and terminals without shell integration are not captured. Interactive input is visible only if echoed into the command's output stream. Task terminal output is available only if VS Code exposes a shell execution for it; task lifecycle capture does not depend on shell integration. Commands launched in a course can print arbitrary data or change directory; VCR scopes the execution by its initial directory and cannot classify its output. The status bar continues to describe editor recording focus. Read-only playback is available in the separate Replay extension.

Validate setup

Select Validate setup on a course card to check that upstream and origin exist and that this VS Code window has successfully written captures using the current recording configuration. Each check shows ? (not yet verified), a green check (passed), or a red error. Hover an indicator for details. Results describe the last validation; select the action again to refresh them.

If no captures have been observed in this window, open a course text file here, edit it, and rerun validation. A rerun without captures reports a possible recording issue. Old recordings and other windows do not prove that this window is recording. Configuration changes require reloading VS Code. These checks do not verify remote access, repository ownership, or successful submission.

VCR records file and folder additions, removals, moves, and renames made through VS Code, including unopened files and empty folders. Moves/renames record paired source and destination events; only endpoints inside enrolled courses are saved. Folders are recorded by path without recursively copying their contents. External operations in the open workspace are observed through filesystem watchers (moves appear as removal/addition). VS Code watcher exclusions and coalescing apply, so this is not a complete filesystem audit. An operation may have both workspace and watcher observations. Recording requires VCR to be active.