AIMax Viewer

VS Code extension that provides automatic HTML/Markdown viewing at startup and an internal browser for localhost development.

Why use AIMax Viewer instead of external browser?

• Stay focused - Opens inside VS Code, no context switching
• Navigation - Toolbar with reload, back/forward buttons
• File browser - Dropdown to quickly switch between files
• Markdown support - .md files rendered as styled HTML automatically
• AI integration - Quick access buttons for terminal and Claude Code
• Deep links - vscode:// URI protocol for automation

Features

1. Auto-Open at Startup

Automatically displays your home page when VS Code opens. Configurable via aimaxViewer.startup.mode.

2. Two Panel Types: Home vs Browser

The extension provides two distinct ways to view content, each with different capabilities:

Technical explanation:

• Home Panel reads the HTML file directly and injects it into a VS Code webview. External links (https://...) are intercepted and opened in your system browser.
• Browser Panel loads content via an iframe with sandbox restrictions. The iframe cannot navigate to external origins for security reasons.

3. Artifacts Browser

Browse all HTML and Markdown files in your configured folders with a dropdown selector or sidebar TreeView. Files are sorted by modification date (newest first).

• 📄 HTML files - displayed as-is
• 📝 Markdown files - automatically converted to styled HTML

4. Sidebar TreeView

A dedicated sidebar panel shows all your artifacts organized by folder. Quick access buttons in the panel header for Terminal and Claude Code.

5. Multi-Folder Support

Configure multiple artifact folders via aimaxViewer.browser.folders. Each folder appears as a separate group in the dropdown and TreeView.

{
  "aimaxViewer.browser.folders": [
    { "label": "Artifacts", "path": "Artifacts" },
    { "label": "Reports", "path": "reports" }
  ]
}

6. Markdown Rendering

Markdown files (.md) are automatically converted to HTML when served. Supported features:

• Headings (H1-H3)
• Bold, italic, strikethrough
• Tables with alignment
• Bullet and numbered lists
• Links and images
• Horizontal rules
• Code blocks (inline)

Just create a .md file in Artifacts/ and it will appear in the dropdown with the 📝 icon.

7. Status Bar Quick Access

A $(home) icon in the status bar provides one-click access to your Home page.

8. Multi-Tab Support

Each artifact opens in a new tab by default. Configure with aimaxViewer.panels.multiTab.

9. Presenter Mode

Present HTML slide decks directly from VS Code. The presenter opens in your system browser with two synchronized windows:

• Audience Window - Clean slide view for projection
• Presenter Window - Current slide, next slide preview, speaker notes, thumbnail carousel, timer

How to use:

1. Right-click an HTML file in Explorer -> "Present with AIMax Viewer"
2. Or from the AIMax browser hamburger menu -> "Present in Browser"
3. Or right-click in Artifacts/Recents sidebar -> "Present"

Slide format: Your HTML file should use <section> elements for slides. Add .speaker-notes elements inside sections for speaker notes.

Keyboard shortcuts (in the presenter window):

• ← / → - Navigate slides
• F - Toggle audience fullscreen
• T - Start/stop timer
• Home / End - First/last slide

10. Content Security Policy (CSP) for CDN Resources

By default, the viewer uses permissive mode allowing common CDN domains:

• fonts.googleapis.com / fonts.gstatic.com - Google Fonts
• cdn.jsdelivr.net - Chart.js, Vue, React
• cdnjs.cloudflare.com - Cloudflare CDN
• unpkg.com - npm packages

CSP Modes:

Example: Using Google Fonts in artifacts

<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&display=swap" rel="stylesheet">

This now works out-of-the-box in permissive mode!

How to configure CSP settings:

1. Via VS Code Settings UI (recommended):

   • Cmd+, (macOS) or Ctrl+, (Windows/Linux)
   • Search for "aimax csp"
   • Set CSP Mode to strict, permissive, or custom
   • If using custom, edit CSP Allowed Domains list

2. Via settings.json:

   {
     "aimaxViewer.csp.mode": "custom",
     "aimaxViewer.csp.allowedDomains": [
       "fonts.googleapis.com",
       "fonts.gstatic.com",
       "your-cdn.example.com"
     ]
   }
   

Note: Settings are in VS Code's user/workspace settings, not in the extension files.

11. vscode:// URI Handler

Deep links for use in HTML artifacts or external tools:

vscode://aimax.aimax-viewer/openBrowser?http://localhost:8080
vscode://aimax.aimax-viewer/openHome

Installation

Quick Install (Recommended)

1. Download the latest .vsix from Releases
2. In VS Code: Cmd+Shift+P (macOS) or Ctrl+Shift+P (Windows/Linux)
3. Type "Extensions: Install from VSIX..." and select the downloaded file
4. Reload VS Code

Build from Source (Developers)

git clone https://github.com/maxturazzini/aimax-viewer.git
cd aimax-viewer
npm install
npm run compile
npx vsce package --allow-missing-repository

Then install the generated .vsix file as above.

Configuration

Commands

Usage with AI Agents (Claude Code, Copilot, etc.)

AIMax Viewer exposes commands via vscode:// URI protocol, enabling any AI agent running in VS Code to display content directly in the editor.

Available URI Commands

Practical Examples

1. Show an HTML artifact:

open "vscode://aimax.aimax-viewer/openBrowser?http://127.0.0.1:3124/Artifacts/2026-01-10_report.html"

2. Show a Markdown file (auto-converted to HTML):

open "vscode://aimax.aimax-viewer/openBrowser?http://127.0.0.1:3124/Artifacts/analysis.md"

3. Show a local dev server:

open "vscode://aimax.aimax-viewer/openBrowser?http://localhost:5173"

Configuration for Claude Code

Add to your project's CLAUDE.md:

Artifact Viewer

When creating HTML or MD files in Artifacts/, display them with: open "vscode://aimax.aimax-viewer/openBrowser?http://127.0.0.1:3124/Artifacts/<filename>"

Naming convention: YYYY-MM-DD_descriptive-slug.html or .md

IMPORTANT: Never use external browser - always use vscode:// protocol.

Getting Started

Create an Artifacts/ folder in your workspace with an index.html file. Check the guides in Artifacts/guide_en.md and Artifacts/guide_it.md for detailed documentation.

Toolbar Buttons

Requirements

• VS Code 1.80.0+
• Workspace with Artifacts/ folder

License

MIT License - Copyright (c) 2024-2026 Max Turazzini

AI, MAX