ODSS VS Code Extension

Records and replays VS Code and Cursor editing sessions, terminal interactions, diagnostics, and AI-assisted code changes using the Open Developer Session Stream (ODSS) container format.

Overview of ODSS: Structured Stream, Not Video

ODSS (Open Developer Session Stream) / ODSF is not a video recording. It does not capture pixels, encode screen frames into MP4/WebM files, or record display buffers.

Instead, it is a deterministic, structured event log of everything that occurred during a development session:

• Text & Buffer State: Exact character-level document edits, open/close lifecycles, and periodic content-addressed snapshots.
• Developer Focus: Cursor coordinates, multi-selection ranges, scroll bounds, and active editor tab changes.

• Tooling & Language Intelligence: Language server diagnostics and debug session markers.
• AI Attribution: Explicit markers for AI-generated code proposals and whether each hunk was active, retained, or reverted.

Why Structured Data Over Video?

1. Interactive and Inspectable: Because replay operates on real text documents and terminal buffers, you can pause at any sequence, select text, inspect syntax trees, search logs, and run diffs against live workspace files.
2. Compact & Compressible: Capturing semantic keystrokes and diffs takes megabytes per hour rather than gigabytes of video bitrate.
3. Random-Access Determinism: Instantaneous seeking to any event sequence without decoding intervening video frames.

The Replay Experience

The ODSS playback engine drives VS Code's editor, virtual filesystem (odss-fs://), and pseudoterminals in real time or at accelerated speeds (0.5x to 4x). It renders paced typing, cursor drift, scroll framing, and terminal activity—producing a video-like replay experience directly inside a real editor environment.

Recording Features

1. Starting a Recording Session

• Command: Ctrl + Shift + P, ODSS: Start Recording (odss.startRecording)
• Container Path Resolution:
  • When a workspace folder is open, sessions are stored in .odss-sessions/<timestamp>-<sessionId>/ at the workspace root.
  • When no workspace is open, the extension falls back to VS Code's global storage directory: <globalStorage>/odss-sessions/<sessionId>/.
• Status Indicator: An item appears in the status bar showing $(sync~spin) ODSS... while initializing, then switches to $(record) ODSS Recording once active.
• Concurrency Guard: Attempting to start a recording while one is already active triggers an explicit error dialog.

2. Stopping a Recording Session

• Command: Ctrl + Shift + P, ODSS: Stop Recording (odss.stopRecording)
• Teardown Sequence:
  1. Closes open terminal instances first to deliver terminal.close events cleanly over IPC while the child is alive.
  2. Disposes all editor event forwarders.
  3. Sends stop to the child process and awaits final flush of the append log and snapshot index.
  4. Terminates the child process and hides the status bar item.

Replay Features

1. Opening and Mounting a Replay

• Command: Ctrl + Shift + P, ODSS: Open Replay Session… (odss.openReplaySession)
• Session Picker (session-picker.ts):
  • Scans .odss-sessions/ in the workspace root, parsing each session's manifest.json.
  • Displays relative start time, duration, and session ID in a QuickPick menu sorted with newest sessions first.
  • Includes a $(folder-opened) Browse… entry to open sessions stored elsewhere.
• Launch Targets:
  • Open in New Window (Recommended): Spawns a dedicated VS Code window mounted to the replay workspace.
  • Open in Current Window: Replaces the current window's workspace with the replay filesystem.
  • Add to Current Workspace: Mounts the session folder as an additional workspace folder in the existing window.
• Auto-Detection: When VS Code opens with an odss-fs workspace URI, the extension detects the session authority and launches playback automatically.
• Integrity Check: Verifies event hash chains and cryptographic signatures on load.

2. Virtual File System (odss-fs://)

Playback runs entirely inside an in-memory FileSystemProvider registered under the odss-fs scheme:

• Non-Destructive: Replayed edits and file state transitions are isolated in memory. Local disk files are never overwritten.
• Authority Format: odss-fs://session-<sessionId>/path/to/file.ts.
• Read-Only Guarantee: Registered with isReadonly: true so the user cannot accidentally modify playback documents.
• Clean Teardown: Unmounting a session purges the in-memory tree for that session authority.

3. Playback Controls

• Play / Resume: ODSS: Resume Replay (odss.resumeReplay)
• Pause: ODSS: Pause Replay (odss.pauseReplay)
• Stop and Close: ODSS: Stop and Close Replay (odss.stopReplay)
• Playback Speed: ODSS: Set Replay Speed… (odss.setReplaySpeed) allows selecting 0.5x, 1x, 2x, or 4x.
• Seek to Sequence: ODSS: Seek Replay Event Number… (odss.seekReplay) prompts for an event number (0..total) and jumps directly to that state.
• Go to First Sequence: ODSS: Go to First Sequence (odss.goToFirstSeq) jumps to sequence 0 (session start) while preserving the current playing or paused state.
• Interactive Control Menu: ODSS: Replay Controls… (odss.replayControls) opens a QuickPick menu with playback actions. This menu also opens whenever you click the replay status bar item.

4. Frame-by-Frame Keyboard Navigation

• Command: Ctrl + Shift + P, ODSS: Toggle Replay Keyboard Navigation (odss.toggleKeyboardControl)
• Activating arrow navigation automatically pauses playback to let you step through events manually. Exiting navigation resumes playback if it was playing before.
• Keybindings (active when keyboard navigation is enabled): | Key | Command | Description | | --- | --- | --- | | Right Arrow | odss.stepForward | Steps forward by one sequenced event. | | Left Arrow | odss.stepBackward | Steps backward by one event using the hybrid re-derive model. | | Home | odss.goToFirstSeq | Jumps back to sequence 0. | | Escape / Enter | odss.toggleKeyboardControl | Exits keyboard navigation mode. |

5. Editor Replay and Visual Feedback

• Document Sync Synchronization: Edits written to odss-fs await VS Code's internal text document model synchronization (waitForDocumentSync) before decorations are calculated, eliminating race conditions.
• Edit Highlights:
  • Single-line edits show a blue left-border highlight for 1.5 seconds.
  • Multi-line or significant text insertions display a transient green hunk highlight for 2.5 seconds.
• Cursor and Selection Playback: Recreates single and multi-cursor selections in real time.
• Adaptive Auto-Scrolling:
  • Micro-drifts (within half a viewport) use TextEditorRevealType.Default to prevent view snapping.
  • Larger movements center the target range with InCenterIfOutsideViewport.
  • Large hunk insertions clamp the reveal range to startLine + 5 so the viewport stays at the beginning of the edit rather than snapping to the bottom.
  • Can be toggled with ODSS: Toggle Replay Auto-Scrolling (odss.toggleScroll) or configured via settings.
• Diagnostics Replay: Language server diagnostics (errors, warnings, info, hints) are restored into VS Code's Problems panel and inline squiggles via a dedicated DiagnosticCollection.

6. AI Diff Attribution and Historical Views

The extension provides visual tracking for code changes generated by AI assistants:

• Change Status Line Decorations (change-status-decorations.ts):
  • Highlights lines based on change lifecycle using native VS Code theme colors:
    • Active (↻): Blue selection background tint (editor.selectionBackground) and blue gutter marker.
    • Retained (✓): Green diff insertion tint (diffEditor.insertedTextBackground) and green gutter marker.
    • Reverted (✗): Red diff removal tint (diffEditor.removedTextBackground) and red gutter marker.
• Persistent Deleted Code Windows (persistent-diff-decorations.ts):
  • Renders deleted pre-edit code using VS Code's native Comments API (CommentThread).
  • Displays a clean, dedented code block anchored directly at the edit line showing what code existed prior to the AI change.
  • Displays a status title (e.g., 🔴 Deleted — original code before this AI edit was accepted).

8. Status Bar Heads-Up Display

The replay status bar item (formatReplayStatusBarText) renders dynamic state:

$(play) ODSS Replay [document.edit] [█████░░░░░] 240/480 (Arrow Nav)

• State Icon: $(play) for playing, $(debug-pause) for paused, $(sync~spin) for loading.
• Active Event Type: Displays the current event without version tags (e.g., [document.edit], [terminal.output], [cursor.move]).
• Visual Progress Bar: 10-segment block progress (█████░░░░░).
• Sequence Counter: Current sequence vs. total sequence count (240/480).
• Mode Indicator: Appends (Arrow Nav) when keyboard navigation is engaged.
• Clickable: Clicking the status item opens the ODSS: Replay Controls… menu.

Command Reference