A browser-based tool that records user interactions with a website and generates LLM-optimized text transcriptions of the actions performed. Perfect for creating reproducible bug reports that AI assistants can understand.
- Records mouse clicks, keyboard input, scrolling, and more
- Outputs human-readable, LLM-friendly text transcripts
- Real-time streaming to console during recording
- Configurable event categories
- Privacy-aware password masking
- Zero dependencies in production
- Works in any modern browser
npm install contextscriptimport { ContextScript } from 'contextscript';<script type="module" src="https://unpkg.com/contextscript/ContextScript.js"></script>Or use jsdelivr:
<script type="module" src="https://cdn.jsdelivr.net/npm/contextscript/ContextScript.js"></script>Download ContextScript.js and the modules/ folder, then include locally:
<script type="module" src="ContextScript.js"></script>After including the script (via npm, CDN, or local file), you can start recording immediately.
| Shortcut | Action |
|---|---|
Cmd+Shift+: (Mac) / Ctrl+Shift+: (Windows) |
Toggle recording on/off |
Cmd+Escape (Mac) / Ctrl+Escape (Windows) |
End recording |
Control recording from the developer console:
ContextScript.start() // Start recording
ContextScript.end() // End recording and show transcript// Start recording
ContextScript.start();
// ... user performs actions ...
// End and get transcript
const transcript = ContextScript.end();
console.log(transcript);Toggle which events are captured via the console:
ContextScript.help // Show all available options
ContextScript.mouse = false // Disable mouse/click capture
ContextScript.keyboard = false // Disable keyboard capture
ContextScript.scroll = false // Disable scroll capture
ContextScript.clipboard = false // Disable clipboard events
ContextScript.form = false // Disable form events
ContextScript.window = false // Disable window events
ContextScript.dragdrop = false // Disable drag & drop
ContextScript.media = false // Disable video/audio events
ContextScript.touch = true // Enable touch events (off by default)
ContextScript.pointer = true // Enable pointer events (off by default)
ContextScript.navigation = false // Disable URL navigation tracking (on by default)
ContextScript.developer = false // Disable console/error capture (on by default)ContextScript.maskPasswords = true // Mask password input with stars (default: true)
ContextScript.maskPasswords = false // Capture actual password characters// Disable categories before recording
ContextScript.mouse = false;
ContextScript.scroll = false;
// Or use the config API
ContextScript.config.setEnabled('mouse', false);
ContextScript.config.isEnabled('keyboard'); // true
ContextScript.config.getEnabledCategories(); // Set { 'mouse', 'keyboard', ... }
// Start recording with current config
ContextScript.start();- Click (single, double, right-click)
- Hover states with duration
- Context menu triggers
- Typed text (batched for readability)
- Special keys (Enter, Tab, Escape, arrows)
- Backspace/delete with character count
- Select-all and delete combinations
- Scroll direction and distance
- Debounced for readability
- Copy with selected text content
- Cut with selected text content
- Paste operations
- Input focus/blur
- Select dropdown changes
- Checkbox/radio toggles
- Text selection
- Form submit/reset
- File input changes
- Tab focus/blur (switching tabs)
- Page visibility changes
- Window resize
- Fullscreen changes
- URL path changes (pushState/replaceState)
- Hash changes
- Browser back/forward (popstate)
- Drag start/end with duration
- Drop zone enter/leave
- File drops with count
- Video/audio play/pause
- Seeking with debounce
- Volume changes
- Mute/unmute
- Tap and double-tap
- Long press with duration
- Swipe with direction
- Multi-touch gestures
- Pinch zoom (iOS)
- Unified mouse/touch/pen input
- Drag with distance and duration
- Pen pressure support
- Console output (log, warn, error)
- Network request failures
- Uncaught JavaScript errors
The transcript is formatted for optimal LLM consumption:
Recording started...
Clicked button#submit-form > div.form-container > main#app
(1.2s later)
Typed "Hello World" in input#username
Pressed Enter
Scrolled down 450px on div#content
(2.5s later)
Clicked a#nav-home.active > nav.main-nav > header#header
Recording ended. Total duration: 8.3s
Features:
- CSS selector paths for clicked elements
- Time gaps shown for context
- Typed text grouped for readability
- Total recording duration
| Method | Description |
|---|---|
ContextScript.start() |
Begin recording |
ContextScript.end() |
End recording and show transcript |
ContextScript.end({ silent: true }) |
End recording and return transcript without UI |
ContextScript.isRecording |
Boolean indicating recording state |
ContextScript.getTranscript(format) |
Get transcript without ending (format: 'plaintext', 'json', 'xml', 'xmltags', 'markdown') |
ContextScript.getEvents() |
Get raw events array |
ContextScript.prompt(options) |
Show instruction overlay and optionally start recording (see AGENT_README) |
ContextScript.help |
Show available options in console |
ContextScript.shortcut |
Get or set the launch shortcut (default: 'Cmd+Shift+:') |
ContextScript.resetShortcut() |
Reset the launch shortcut to default |
| Shortcut | Description |
|---|---|
Cmd+Shift+: (Mac) / Ctrl+Shift+: (Windows) |
Toggle recording on/off |
Cmd+Escape |
End recording |
| Property | Description |
|---|---|
ContextScript.config |
Access to Configuration instance |
ContextScript.streamToConsole |
Boolean to enable/disable live streaming (default: true) |
| Method | Description |
|---|---|
isEnabled(category) |
Check if category is enabled |
setEnabled(category, bool) |
Enable/disable a category |
hasCategory(category) |
Check if category exists |
getState() |
Get all category states |
getEnabledCategories() |
Get Set of enabled categories |
showHelp() |
Display help in console |
- Password input is automatically masked with
*characters - Sensitive form fields are identified by
type="password" - Disable password masking only for testing:
ContextScript.maskPasswords = false - No data is sent to external servers - all processing is local
- Bug Reports — Generate transcripts that help AI assistants understand and reproduce bugs with exact action sequences and timing
- QA Documentation — Record manual test procedures as references for automation engineers writing Playwright/Cypress tests
- UX Analysis — Analyze user interaction patterns; record logs of user interations in human readable plaintext.
- AI Assistant Context — Paste transcripts into Claude/ChatGPT for debugging help with full action context
- Tutorial Generation — Convert recorded interactions into step-by-step documentation
- Performance Monitoring — Enable
developerevents to correlate user actions with console errors and network failures
ContextScript can be used with AI coding agents to capture user demonstrations for debugging and testing. See AGENT_README.md for integration workflows, the prompt() API, and complete examples using Playwright.
ContextScript supports silent operation for automation tools and LLMs that need to capture user interactions programmatically.
// End recording without UI dialog
const transcript = ContextScript.end({ silent: true });
// Get transcript in specific format: 'plaintext' (default), 'json', 'xml', 'xmltags', 'markdown'
const json = ContextScript.end({ silent: true, format: 'json' });
// Peek at transcript without ending
const current = ContextScript.getTranscript('json');
// Get raw events array
const events = ContextScript.getEvents();The pattern is the same for any automation tool—only the JS execution syntax differs:
const { chromium } = require('playwright');
const browser = await chromium.launch({ headless: false });
const page = await browser.newPage();
await page.goto('https://your-app.com');
// Start recording
await page.evaluate(() => window.ContextScript.start());
// Wait for user to finish (Cmd+Escape to end)
await page.waitForFunction(() => !window.ContextScript.isRecording);
// Capture transcript
const transcript = await page.evaluate(() =>
window.ContextScript.getTranscript('json')
);If the browser closes while recording, the transcript is automatically dumped to console with clear markers for capture by automation tools.
MIT License - see LICENSE file for details.
Contributions are welcome! See DEVELOPMENT.md for setup instructions, architecture details, and contribution guidelines.