This document provides a high-level introduction to the ScriptCat browser extension codebase, covering its architecture, core components, and technology stack. ScriptCat is a Manifest V3 browser extension that functions as a powerful userscript manager with advanced features like background script execution, scheduled tasks, and an integrated AI agent subsystem.
For detailed information about specific subsystems, see:
ScriptCat is a Manifest V3 userscript manager based on Tampermonkey's design philosophy and is fully compatible with Tampermonkey scripts README.md28-29 It manages userscript installation, execution, and synchronization across multiple execution contexts.
Core Capabilities:
Sources: README.md28-63 package.json2-4 src/manifest.json1-10 src/app/const.ts1-20
The extension follows the Manifest V3 standard, utilizing a Service Worker for background orchestration and specialized environments for script execution. It utilizes a distributed-system model across five distinct isolated contexts.
Key Architectural Components:
src/service_worker.ts) managing script lifecycle, resource caching, and message routing src/manifest.json11-14 AGENTS.md58src/sandbox.html) for running scripts in an isolated manner using with(arguments[0]) and handling cron scheduling src/manifest.json48-50 AGENTS.md62For a deep dive into component interactions, see Extension Architecture.
Sources: src/manifest.json1-57 AGENTS.md42-73 docs/develop.md43-58
ScriptCat supports a multi-context execution model to provide both security and deep page integration.
| Context | Source File | Description | Access Level |
|---|---|---|---|
| Content | src/content.ts | Bridge between SW and Inject script. | Isolated world, chrome.userScripts AGENTS.md59 |
| Inject | src/inject.ts | Runs in the page's "Main World". | Access to unsafeWindow AGENTS.md60 |
| Offscreen | src/offscreen.ts | DOM-capable background. | Persistent background scripts AGENTS.md61 |
| Sandbox | src/sandbox.ts | Isolated execution environment. | Background/Scheduled script logic AGENTS.md62 |
Scripts are matched to URLs using patterns like @match, @include, and @exclude. The extension requests broad permissions, including userScripts and scripting, to facilitate these execution paths src/manifest.json27-45
For details on terminology and data structures, see Core Concepts and Terminology.
Sources: src/manifest.json27-57 AGENTS.md42-73 README.md43-50
ScriptCat is built with a modern stack, having recently migrated to Tailwind CSS v4 and shadcn/ui.
| Category | Technology |
|---|---|
| Framework | React 19 package.json53 AGENTS.md21 |
| UI Library | shadcn/ui + Tailwind CSS v4 AGENTS.md21 |
| Database | Dexie.js (IndexedDB) package.json43 |
| Editor | Monaco Editor package.json51 |
| Bundler | Rspack package.json72-73 |
| Testing | Vitest & Playwright package.json71-111 |
Build & Development:
pnpm run dev: Starts the development server using Rspack package.json11pnpm run build: Production Rspack build package.json14pnpm run lint: Runs a comprehensive linting suite including i18n and type checks package.json17Sources: package.json8-113 AGENTS.md21 docs/develop.md9-30
The extension provides several user-facing interfaces defined in the manifest:
src/options.html serves as the primary dashboard for script management and configuration src/manifest.json7-10src/popup.html provides quick access to scripts active on the current tab src/manifest.json17-22src/install.html is used to confirm userscript installation src/manifest.json53-56Sources: src/manifest.json7-57