mallurun for Visual Studio Code

mallurun is a quirky, delightfully responsive VS Code extension that automatically displays an animated GIF reaction in a dedicated Webview panel whenever you run or debug code.

🌟 Overview

Tired of staring at dry terminal logs? mallurun brings instant joy and visual energy to your daily development routine by playing animated GIF reactions whenever you execute code through supported VS Code workflows.

Supported Execution Scenarios

1. Run and Debug Button & F5: Automatically reacts when a root debug session starts across any programming language (Node.js, Python, C++, Rust, Go, Java, C#, etc.).
2. Debug Session Concluded: Optional reactions when a debug session finishes (mallurun.triggerOnDebugEnd), carefully formulated without making unsubstantiated claims of program success.
3. Integrated Terminal Execution: Observes command executions in terminals with VS Code Shell Integration (PowerShell, Bash, Zsh) against configurable pattern whitelists (python, node, cargo run, npm start, etc.).
4. Third-Party Execution Extensions:
   • Code Runner (formulahendry.code-runner): Run with Code Runner via mallurun: Run with Code Runner (with Reaction).
   • Python (ms-python.python): Detects Python execution in terminal and debugging via debugpy.
   • C/C++ (ms-vscode.cpptools): Detects build tasks and debugging launches.
   • Java (vscjava.vscode-java-debug): Detects Java launch sessions.
5. mallurun-Managed Execution: Safely execute the current active editor file with path-quoting and instant reaction via mallurun: Run Current File (with Reaction).
6. Task Execution: Captures build, test, and run tasks triggered from the task runner.

✨ Key Features

• Dedicated Webview Panel: Lightweight, dark-themed panel styled with VS Code CSS custom properties (--vscode-editor-background, --vscode-foreground).
• Aspect Ratio & Sizing: Automatically scales large GIFs, centers content, and preserves aspect ratio across split-screen, horizontal, or vertical layouts.
• Smart Panel Reuse: Automatically updates and reveals the existing panel on subsequent executions rather than opening redundant editor tabs.
• GIF Playback Restart Guarantee: Every new reaction restarts the GIF animation from frame zero, even if the same file is replayed consecutively.
• Transparent GIF Support: Handles transparent backgrounds natively without white borders or artifacts.
• Interactive UI Controls:
  • Reactions Paused Status Banner: Prominently warns when reactions are disabled, with an instant "Enable Now" action button.
  • Quick Category Preview Pills: Clickable pills (Coding, Success, Funny, Chaos) to test reactions instantly.
  • Dismiss & Close Controls: Easily dismiss the active reaction or close the panel directly from the UI.
• Resilient Asset Management:
  • Preloaded with 4 original, genuine looping GIF89a pixel-art animations.
  • Supports adding custom GIFs to the built-in folders or pointing to any external directory via mallurun.customGifsPath.
  • Non-crashing empty and error states with troubleshooting guidance.
• Safe Execution Architecture:
  • Child-session deduplication (ignores worker threads and child debug sessions).
  • Configurable repeat policies (debounce, throttle, always).
  • Strict offline Content Security Policy (zero remote requests).
  • Workspace trust safeguards against running untrusted repository scripts.

🎮 Commands

Access these commands from the Command Palette (Ctrl+Shift+P / Cmd+Shift+P):

⚙️ Configuration Settings

Configure mallurun in Settings (Ctrl+, or Cmd+,) by searching for mallurun:

🔍 Integrated Terminal Detection & Shell Integration

How It Works

mallurun uses the official, stable VS Code Shell Integration API (vscode.window.onDidStartTerminalShellExecution). When active, VS Code communicates directly with your shell (PowerShell 7+, Bash, Zsh) to observe genuine command executions.

What Is Observable vs Not Observable

• ✅ Observable: Real command lines executed through shells with Shell Integration enabled.
• ❌ Not Observable: Raw keystrokes in terminals without Shell Integration. VS Code does not expose arbitrary keystroke listeners or stdout scraping via stable extension APIs.
• ❌ Terminal Creation Is Not Execution: mallurun explicitly does not treat opening a new terminal tab as code execution.

Fallbacks for Environments Without Shell Integration

1. mallurun-Managed Execution: Use mallurun: Run Current File (with Reaction) (mallurun.runCurrentFile) to run files with safe path quoting and guaranteed reactions.
2. Tasks & Debugging: Use F5, Run and Debug, or VS Code tasks (npm test, cargo run, etc.).
3. Diagnostics: Run mallurun: Show Diagnostics to inspect whether Shell Integration is active in your terminal.

📁 Adding Custom GIFs

You can customize the GIF library in two ways:

Method 1: Custom Folder Setting (Recommended)

1. Set mallurun.customGifsPath in your settings to any local folder (e.g. C:\Users\username\Pictures\MyGifs or /home/username/gifs).
2. Put .gif files directly into that folder, or organize them into subfolders: success, coding, funny, chaos.
3. mallurun will automatically scan and integrate them!

Method 2: Extension Media Directory

1. Open the reaction panel in VS Code (mallurun: Open Reaction Panel).
2. Click 📁 Open GIFs Folder, or navigate to media/gifs/.
3. Drop your favourite .gif files into any category folder.

🔒 Security & Privacy

mallurun is built following strict VS Code security guidelines:

• 100% Offline: No remote network requests, no asset downloads from third parties, and no external CDNs.
• Strict Content Security Policy: Only local resources from the extension media and explicitly configured custom folders can be rendered.
• No Telemetry or Tracking: Zero user tracking, telemetry, or analytics.
• Safe Command Handling: The file runner performs strict quoting and escaping ("${filePath.replace(/(["\\$])/g, '\$1')}"`) to prevent shell injection.
• Workspace Trust: Declares "capabilities": { "untrustedWorkspaces": { "supported": "limited" } } and prompts for confirmation before executing files in untrusted workspaces.
• Zero Credential Exposure: Diagnostics reports contain strictly non-sensitive operational data.

🛠️ Development & Testing

Prerequisites

• Node.js (v18+)
• npm (v9+)
• Visual Studio Code

Building & Running

# Install dependencies
npm install

# Compile TypeScript
npm run compile

# Run automated unit verification suite
npm test

Running in Extension Development Host

1. Open this repository in VS Code.
2. Press F5 (or go to Run and Debug -> Run Extension).
3. In the new window that opens, run mallurun: Show Random Reaction or press F5 to trigger a reaction.

Packaging a VSIX

npm run package

Generates a distributable package: mallurun-0.3.0.vsix.

🧪 Tested Workflows Summary

📄 License & Asset Attribution

Distributed under the MIT License. See LICENSE for full details.

Included GIF Assets

The animated GIF reactions located in media/gifs/ (cats-dancing-ai-cat.gif, dance-mohanlal.gif, dancing-suresh.gif, guhan-mammootty.gif) are dynamically loaded, categorized, and randomly displayed whenever program execution events occur. Custom GIF files can also be added directly to media/gifs/ or configured via mallurun.customGifsPath.

🐛 Bug Reports & Feedback

If you encounter issues or have suggestions, please open an issue on the mallurun GitHub repository.