🦞 ShadowClaw

A browser-native, fully-featured AI assistant. TypeScript + Web Components + IndexedDB + File System API.

Quick Start

npm install && npm run dev  # Dev server → http://localhost:8888

Open Settings, select a provider (or use browser Prompt API), and start chatting.

Desktop: npm run electron or npm run electron:build for distributable.

What is ShadowClaw?

A fully-functional agent runtime that runs entirely in the browser—no AI processing on a server. Built with TypeScript, it provides:

• Multi-model support: OpenRouter, Anthropic, Google Gemini, AWS Bedrock, Ollama, Llamafile, Mesh LLM, Transformers.js, and browser-native Prompt API
• Web Components UI: Native Custom Elements + TC39 Signals for reactive updates
• Persistent storage: IndexedDB for messages/config, OPFS for files
• Agent tools: File I/O, shell (with optional WebVM), Git, HTTP, JavaScript execution
• Multi-conversation support: Each conversation has isolated chat history, file workspace, and scheduled tasks
• Messaging channels: Browser chat, PeerJS, Telegram Bot API, iMessage bridge (configurable)
• PWA + offline: Service Worker, Web Push notifications, scheduled task execution even when closed
• Desktop app: Electron wrapper with full parity to the web version

Key Features

• Streaming responses — Token-by-token text updates with live chat bubble
• Dynamic context windowing — Token-aware message history (not fixed-size window)
• Tool profiles — Per-model/provider tool customization and system prompt overrides
• Conversation-scoped subagent policy — Per-conversation subagent mode (automatic or manual) with optional pinned provider/model
• Conversation-scoped agent token budget — Optional per-conversation max output tokens override (clamped to selected model limits)
• Conversation-scoped provider runtime overrides — Per-conversation runtime overrides for Bedrock proxy and Llamafile (auth/profile/region/host/mode/offline/port)
• Model registry — Dynamic metadata fetch (context window, modality support)
• Attachment capabilities — Native multimodal delivery with automatic text fallback
• Remote MCP — Discover and execute tools from external MCP servers
• A2UI interactive surfaces — Render responsive UI components (Text, Button, TextField, Row/Column layouts) from agents via PeerJS WebRTC with two-way data binding
• Multi-Agent Shared State — Synchronize agent knowledge across participants using STATE_SNAPSHOT and STATE_DELTA events
• Email integration — IMAP/SMTP support with encrypted credentials
• Web Share Target — Receive files/URLs directly from OS share sheet
• Scheduled tasks — Cron expressions with server-side persistence and Web Push
• Git integration — Clone, branch, merge (with conflict reports), push/pull
• File viewer — Syntax highlighting (locally bundled CSS, no CDN), PDF preview, media playback, Web Share, native/fallback fullscreen, relative image workspace resolving, and configurable iframe embed sanitization; iframe sandbox hardened (no allow-same-origin)
• Files browser — Clipboard-driven Cut/Copy/Paste actions, hidden Paste button when empty, folder self-paste protection, inter-group transfers, and conflict resolution (rename/overwrite)

Architecture

ShadowClaw follows a worker-isolated runtime pattern:

graph TD
  UI["Web Components<br>Chat, Files, Tasks"]
  Orchestrator["Orchestrator<br>State Machine + Queue"]
  Worker["Agent Worker<br>LLM + Tool Loop"]
  Providers["Providers<br>OpenRouter, Bedrock, etc."]
  Tools["Tool Execution<br>Bash, Git, Files, Fetch"]

  UI --> Orchestrator
  Orchestrator --> Worker
  Worker --> Providers
  Worker --> Tools

  DB["IndexedDB<br>Messages, Config, Tasks"]
  FS["OPFS<br>Workspace Files"]
  Orchestrator --> DB
  Orchestrator --> FS

  SW["Service Worker<br>PWA, Push, Scheduling"]
  UI --> SW

Loading

Key design principles:

• Agent in Web Worker — LLM calls, tool execution, and WebVM all run off-main-thread to keep UI responsive
• Message-based protocol — Strict postMessage boundaries between main thread and worker
• Reactive signals — TC39 Signals (via signal-polyfill) drive all UI updates
• Storage isolation — Each conversation gets a workspace (shadowclaw/<groupId>/workspace/); shared config in IndexedDB

Full architecture docs: See Architecture for orchestrator state machine, worker protocol, storage system, context management, and streaming.

Multi-Conversation Support

Each conversation has:

• Independent chat history
• Isolated file workspace
• Scheduled tasks
• Editable MEMORY.md (loaded as system context)
• Optional per-conversation tool tagging
• Optional per-conversation pinned provider/model and max output tokens
• Accessible sidebar with drag-and-drop reordering and clone support
• Unread indicators with pulsing highlights

Last-active conversation persists across reloads. On first launch, a default "Main" conversation is auto-created.

Full guide: docs/architecture/orchestrator.md

Providers & Models

ShadowClaw supports multiple LLM providers with a unified adapter pattern:

Category	Examples	Notes
Cloud	OpenRouter, OpenAI, Anthropic, Google Gemini, AWS Bedrock, Vertex AI	API key required
Local	Ollama, Llamafile, Mesh LLM, Transformers.js	Runs on local server or in-browser
Browser	Prompt API (window.LanguageModel), LiteRT	Experimental, keyless, Gemini Nano

Features:

• Streaming responses (OpenAI + Anthropic formats)
• Adaptive rate limiting with retry-after support
• Dynamic model registry with capability metadata (context, modalities, tool support)
• Multi-format support (OpenAI, Anthropic, Prompt API)
• Prompt API session retry loop & hardware feature probing — automatically probes WebGPU adapter capabilities (requiring shader-f16 support), retries LanguageModel.create() during downloads, and dynamically falls back to WebAssembly CPU (device: "wasm", dtype: "q4") if WebGPU initialization fails or software emulation is detected.
• Polyfill model cache — Service Worker CacheFirst caching strategy stores Hugging Face polyfill model binaries (.onnx, .onnx_data) for offline performance

Setup & details: docs/guides/adding-a-provider.md | docs/subsystems/providers.md

Agent Tools

The agent has access to 50+ tools including:

Category	Tools
Files	read_file, write_file, patch_file, delete_file, move_file, copy_file, create_directory, list_files, open_file, attach_file_to_chat, send_file, search_files, diff_files
Shell	bash (WebVM or just-bash emulator)
Built-in AI	summarize_text, write_text, rewrite_text, proofread_text, detect_language, translate_text (defaults to Active Conversation LLM backend with opt-in local browser Task API polyfill)
Git	git_clone, git_init, git_add, git_unstage, git_commit, git_push, git_pull, git_fetch, git_merge, git_diff, and more
Web	fetch_url, fetch_file, web_search (DuckDuckGo via configurable CORS search proxy and URL templates)
Compute	javascript (sandboxed)
Agents	spawn_subagent (parallel task delegation), ask_user (human-in-the-loop pause)
Time	get_current_time (ISO 8601 or IANA timezone)
Tasks	create_task, list_tasks, update_task, delete_task, enable_task, disable_task, run_task
UI	show_toast, send_notification, clear_chat
Context	update_memory (edits MEMORY.md)
Remote	remote_mcp_list_tools, remote_mcp_call_tool (external MCP servers)
Email	manage_email, email_read_messages, email_send_message
Rooms	create_room, invite_to_room, leave_room, list_room_members
A2UI	list_components, render_component

Testing WebMCP Integration

WebMCP integration: When document.modelContext is available (with navigator.modelContext fallback for Chrome < 152), tools are also registered through the browser's Model Context Protocol (@mcp-b/webmcp-polyfill v3). ShadowClaw provides parseWebMcpInputSchema to normalize input schemas across Chrome 154+ (native object) and Chrome < 154 (DOMString JSON) versions, and getWebMcpTools() to safely query registered tools with graceful degradation.

// get available tools (safely normalizes input schemas across Chrome versions)
var tools = await document.modelContext.getTools();

// format the tool list
var formattedToolsJSON = JSON.stringify(
  tools.map(
    ({ annotations, description, inputSchema, name, origin, title }) => ({
      annotations,
      description,
      inputSchema,
      name,
      origin,
      title,
    }),
  ),
  null,
  2,
);

// list available tools
console.log(formattedToolsJSON);

// get the toast tool
var [toastTool] = tools.filter((v) => v.description.includes("Show a toast"));

// run the toast tool
await document.modelContext.executeTool(
  toastTool,
  '{ "message": "Hello from 🦞 Shadow Claw!"}',
);

Full reference: docs/subsystems/tools.md | docs/subsystems/webmcp.md

Conversations & Messaging Channels

ShadowClaw supports four messaging channels by default:

• br: — In-browser chat
• im: — iMessage bridge
• peer: — PeerJS WebRTC (includes Peer Rooms for multi-agent collaboration)
• tg: — Telegram Bot API

Each channel creates isolated conversations with their own message history and workspace.

Setup & architecture: docs/guides/configuring-messaging-channels.md (setup) | docs/subsystems/channels.md (architecture + custom channels)

Pages System

ShadowClaw includes a Pages sidebar for organizing and viewing workspace content.

• Render markdown & HTML — Save any markdown or HTML file as a page for structured preview, including optional visible YAML frontmatter metadata
• Workspace-relative links — Links and images in pages resolve relative to the workspace
• Page sidebar — Persistent list of saved pages with drag-and-drop reordering and responsive mobile sidebar collapse
• Static Main Site Seeding — Automatically seeds default main pages from the pages/main/ manifest, respecting page suppression rules
• Static Pretty Paths & DSD Pre-rendering — Build-time pre-rendering for pages/routes.json generates static HTML with Declarative Shadow DOM templates for clean URLs across Node.js, Electron, and GitHub Pages (pages flagged for purge are excluded from the output manifest); same-origin links are validated via isPossibleAppRoute so non-app paths fall back to native browser navigation
• Page Suppression — Deleting pages suppresses auto-reseeding (SUPPRESSED_PAGES_LIST) until re-added
• Safe iframe embeds — HTML previews use a configurable iframe host allowlist in Settings, with safe defaults for common embedded content hosts
• Ebook-Style Navigation — Functional Previous/Next pagination controls with HTML-entity decoded frontmatter headers, seamless page transitions, ArrowLeft/ArrowRight keyboard navigation, touch/mouse swipe gestures, and aria-live screen reader announcements
• Pre-rendered Content Override — Optional setting (OVERRIDE_PRERENDER_SKELETON) suppresses Declarative Shadow DOM (DSD) pre-rendered content during boot to eliminate hydration flash
• Declarative Site Configuration — Support for site-config.json enabling template repositories to customize site metadata, branding, custom theme stylesheets, custom element security allowlists, and navigation visibility without modifying core source
• Dynamic Sidebar Navigation Visibility — Runtime toggling of Pages, Chat, Tasks, and Files sidebar tabs via Settings, with automatic fallback routing and build-time DSD navigation attribute synchronization
• Content-Only Publishing — Supports GitHub Pages publishing via the shadow-claw-template template repository that pulls ShadowClaw as a CI-time build dependency.

Pages complement the main group MEMORY (auto-created as MEMORY.md on first setup) which serves as a workspace-scoped system context for the agent. An index.html is also auto-created as the default home page.

WebVM (Optional Alpine Linux)

For advanced bash operations, ShadowClaw includes an optional WebVM (v86 Alpine Linux) that runs in the Web Worker.

• Boot modes: auto (9p, lighter weight), ext2 (full filesystem), or disabled (fallback to JavaScript shell)
• Coordination: Terminal sessions and tool execution share exclusive access with graceful handoffs
• Workspace sync: 9p mode syncs VM /workspace changes back to OPFS so Files view stays in sync
• Interactive terminal: Full shell access via <shadow-claw-terminal> component

Full guide: docs/subsystems/vm.md

Storage & Security

ShadowClaw uses IndexedDB for structured data (messages, config, tasks) and OPFS for files.

Security:

• AES-256-GCM encryption for API keys at rest
• TC39 private fields to prevent accidental leakage via console
• 30-second key expiry for plaintext operations
• No plaintext secrets on disk — encrypted before storage
• Trusted Types enforcement — idempotent "default" policy (src/security/default-trusted-types-policy.ts) registered at boot via theme-init.ts; getPolicy() fallback prevents duplicate-creation errors on module reload
• Custom element security guards — installCustomElementsRegistryGuard and installCustomElementDomGuard prevent unauthorized custom element registration and dynamic DOM injection, strictly enforcing allowlists from site-config.json or storage
• Iframe sandbox & CSP hardening — sandboxed preview iframes omit allow-same-origin by default and apply a nonce-gated Content Security Policy with domain restrictions
• Iframe embed sanitization — DOMPurify-based iframe allowlisting protects markdown and HTML previews, with Settings-backed host patterns and a safe default host list
• SSRF proxy hardening — /proxy blocks non-HTTP/S schemes and private/loopback IP ranges by default; bypassed via --allow-private-proxy flag or the authenticated service-worker JSON format
• Prompt injection defense — external tool outputs (fetch_url, web_search, remote_mcp_call_tool) are structurally wrapped in UNTRUSTED delimiters; system prompt includes explicit anti-injection instructions when untrusted-content tools are active

File I/O:

• OPFS — browser-sandboxed storage (shadowclaw/<groupId>/workspace/)
• Local Folder — user-selected directory via File System Access API
• Centralized write paths — cross-browser fallback for Safari compatibility
• Zip export/import — for conversation backup/restore
• Copy/move safety — folder copy/move operations prevent pasting a folder into itself or one of its descendants, and support inter-group operations with conflict resolution

Full details: docs/architecture/storage.md | docs/subsystems/crypto.md | docs/subsystems/custom-element-security.md

Scheduled Tasks & Web Push

ShadowClaw supports cron-based scheduled tasks with Web Push notifications. Tasks fire even when the app is closed.

• Task expressions use standard 5-field cron syntax
• Task sequences — Execute a single text prompt, or sequentially run a list of agent tools
• Server-side persistence — SQLite database ensures reliable firing (can be toggled via Settings)
• Web Push integration — OS-level notifications when tasks trigger
• Recursion guard — prevents infinite task → notification → task loops
• Client/Server parity — Express dev server and Electron both support full scheduling
• Fresh Context & Subagent isolation — Toggle task execution to bypass conversation history (fresh context) or run isolated in the background (subagent)

Setup & architecture: docs/subsystems/notifications.md

Advanced Features

Remote MCP Integration

Connect external Model Context Protocol (MCP) servers to extend agent capabilities dynamically. Tools from remote servers are discovered and executed transparently.

• Bearer, Basic, and custom header authentication
• OAuth token refresh support
• Automatic reconnection on failure

Full guide: docs/subsystems/remote-mcp.md

Protocol-Agnostic Integrations

Email (IMAP/SMTP), RSS, webhooks, and other integrations via a plugin architecture.

• Encrypted credential storage
• Typed action dispatch
• Configurable plugin catalog

Full guide: docs/guides/protocol-agnostic-integrations.md

Web Share Target

Receive files, URLs, and text directly from your OS share sheet into ShadowClaw.

• Supported on all PWA-capable browsers and Android
• Files are persisted to workspace
• Auto-opens dated conversation with imported files

Full details: manifest.json | src/service-worker/share-target.ts

Tool Profiles & Customization

Create model-specific or task-specific tool profiles to optimize the context window.

• Enable/disable individual tools
• Override system prompt per profile
• Auto-activate profiles by model
• Save custom selections
• Built-in Profile — Default Prompt API profile is restricted to core file and script tools (javascript, list_files, open_file, read_file, write_file)
• Execution-time allowlist enforcement — Tool calls are re-validated at runtime against the active enabled tool list (profile/manual), not only generation-time schema hints
• Shared internet access control — Toggles public internet access (fetch and shell networking) globally for the bash and javascript tools

Full guide: docs/subsystems/tools.md

Attachment Capabilities

Native multimodal delivery with automatic text fallback.

• Model registry fetches capability metadata dynamically
• Attachments sent as native content blocks when supported
• Automatic fallback to OCR/markdown for unsupported formats

Full details: docs/subsystems/attachment-capabilities.md

Dynamic Context & Auto-Compaction

Instead of fixed-size message windows, context is token-aware and adaptive.

• System prompt + max output tokens budgeted first
• Messages walked newest-to-oldest within budget
• Large outputs truncated at line boundaries
• UI progress bar tracks context usage
• Token estimation & cache tracking — Tracks token usage and cache hits/misses across context window
• Auto-compaction triggers at 80% usage

Full details: docs/architecture/context-management.md

Documentation

Architecture docs, subsystem guides, and decision records live in docs/:

• Architecture — Orchestrator, worker protocol, storage, context, streaming
• Subsystems — Shell, VM, git, channels, tools, providers, notifications, Electron, reactive UI, crypto
• Guides — Adding providers, tools, shell commands, pages, channels
• Decisions — ADRs for bundled architecture, TypeScript, Signals, worker-owned VM, IndexedDB

Agent-specific conventions and guardrails: AGENTS.md

E2E test architecture: e2e/README.md

Development

npm run dev                  # Dev server (watch mode)
npm start                    # Express server
npm test                     # Jest (*.test.ts files live next to source)
npm run e2e                  # Playwright E2E tests (e2e/*.test.ts)
npm run e2e:install          # Install Playwright browser binaries
npm run tsc                  # TypeScript type-check
npm run build                # Bundle application via Rolldown + generate service worker
npm run build:service-worker # Generate the Workbox service worker
npm run build:prod           # Production bundle build
npm run format               # Prettier
npm run electron             # Launch Electron desktop app
npm run electron:build       # Build Electron distributable
npm run electron:build:win   # Build Electron for Windows
npm run electron:build:mac   # Build Electron for macOS

License

AGPLv3. Core logic derived from openbrowserclaw (MIT).