# ShadowClaw Documentation > Deeper dives into the systems that make ShadowClaw tick — for humans _and_ agents alike. ## What's in here ### Architecture How the core pieces fit together. | Document | What it covers | | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- | | [System Overview](architecture/overview.md) | High-level architecture, data flow, design philosophy | | [Orchestrator & State Machine](architecture/orchestrator.md) | Main-thread state machine, message queue, invoke/compact lifecycle, EventBus | | [Worker Protocol](architecture/worker-protocol.md) | Worker ↔ main thread messages, tool-use loop, streaming, cancellation | | [Storage System](architecture/storage.md) | OPFS, local folders, write paths, copy/move safeguards, zip export/import, group workspaces, CacheStorage model caching | | [Context Management](architecture/context-management.md) | Token estimation, dynamic windowing, output truncation, auto-compaction, hardware-aware token recommendations | | [Streaming](architecture/streaming.md) | SSE flow, StreamAccumulator, throttling, intermediate responses, proxy passthrough | ### Subsystems Detailed docs for each major subsystem. | Document | What it covers | | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Shell Emulator](subsystems/shell.md) | JS shell via `just-bash` AST evaluation, OPFS bridge, supported commands | | [WebVM](subsystems/vm.md) | v86 Alpine Linux, boot modes, exclusivity guard, terminal bridge, 9p sync | | [Git Integration](subsystems/git.md) | isomorphic-git on native filesystem handles, merge conflicts, credentials | | [Channel System](subsystems/channels.md) | Channel registry, browser/Telegram/iMessage channels, router, multi-channel flow | | [Remote MCP](subsystems/remote-mcp.md) | External MCP servers, tool discovery, authentication, JSON-RPC protocol, OAuth reconnection | | [Accounts & Credentials](subsystems/accounts.md) | Service account management, credential storage, auth bridges | | [Crypto & Secrets](subsystems/crypto.md) | AES-256-GCM key storage, runtime key handling, environment hardening; idempotent default Trusted Types policy | | [Tools & Profiles](subsystems/tools.md) | Tool definitions, execution dispatch, declarative tool executor, centralized guards, profiles, tool configuration panel, adding new tools | | [Agent Skills](subsystems/skills.md) | Workspace-local skill discovery, slash-command routing, declarative tool execution pipelines, output/toast suppression, discovery index generation (.well-known/agent-skills/index.json), resources, and static publishing | | [Notifications & Scheduling](subsystems/notifications.md) | Web Push, VAPID, server-side SQLite scheduler, recursion guards | | [Providers & Model Registry](subsystems/providers.md) | LLM provider registry, adapter pattern, Prompt API (default with polyfills), LiteRT-LM WebGPU, dynamic CPU/WASM fallback, model registry & capability detection, CacheStorage model downloads, and 30s auto-closing dialogs | | [Electron Desktop](subsystems/electron.md) | Desktop app architecture, in-process server, power management | | [Reactive UI & Component Library](subsystems/reactive-ui.md) | Signals, `ShadowClawElement`, `reconcileList`, Web Components, stores, modular ESM package exports (`./components`, `./utils`), dynamic Rolldown library discovery, and Storybook workbench | | [Attachment Capabilities](subsystems/attachment-capabilities.md) | MIME-aware attachment handling and native vs fallback delivery | | [Chat Template Sanitizer](subsystems/sanitizer.md) | Strip control tokens and structural markers from local model output | | [A2UI Interactive Surfaces](subsystems/a2ui.md) | A2UI v1.0 catalog renderer, component rendering, PeerJS surface delivery, data binding, and Storybook workbench coverage for all 18 components | | [AGUI Events & Adapter](subsystems/agui.md) | Translates orchestrator EventBus events to standardized AG-UI protocol events for UI visibility | | [Trusted Types Tinyfill](subsystems/trusted-types-tinyfill.md) | Polyfill for Trusted Types API, browser compatibility, security rationale | | [Email Integration](subsystems/email.md) | IMAP/SMTP support with encrypted credentials | | [WebMCP](subsystems/webmcp.md) | Browser's Model Context Protocol integration and tool execution, supporting Chrome 154+ object input schemas, getWebMcpTools querying, and graceful degradation | | [Web Share Target](subsystems/share-target.md) | OS share sheet integration receiving files, URLs, and text into OPFS workspaces via PWA Web Share Target API | | [Pages System](subsystems/pages.md) | Workspace-relative pages rendering, sidebar navigation, static site seeding, pretty paths, same-origin route validation, and production asset inlining | | [Theming & Stylesheets](subsystems/theming.md) | Custom site theming, `theme.stylesheet`, CSS custom properties, layout/shell visibility tokens, light DOM slotted navigation styling, and preview iframe theme sync | | [Custom Element Security](subsystems/custom-element-security.md) | Custom element registry & DOM guards, allowlists, script descriptors ({ src, hasInit }), iframe sandbox policies, and nonce-gated CSP | | [CLI & Static Site Publishing](subsystems/cli.md) | `shadow-claw` CLI commands (`agent`, `build`, `dev`, `serve`, `server`, `init`, `clients`, `send`, `backup`, `tasks`, `mcp`, `skills:index`), headless agent participant, dual-root path resolution, and npm packaging | | [Control Plane & Client Bridge](subsystems/control-plane.md) | SSE, WebSocket, and WebRTC DataChannel control plane for CLI driving, headless automation, and persistent browser execution surfaces | | [Stateless MCP Server](subsystems/mcp-server.md) | Official Stateless Model Context Protocol (2026-07-28) server for external agent hosts, featuring modular built-in tool definitions (`shadowclaw_server_*`), host-native CLI agent tools (`shadowclaw_local_*`), client tool name centralization, and dynamic browser tool relaying (`shadowclaw_client_*`) | | [File Backup Subsystem](subsystems/backup.md) | Remote workspace and OPFS file backups to server storage | | [OpenAPI & Endpoint Discoverability](subsystems/openapi.md) | Official OpenAPI 3.1 specification, interactive Scalar documentation UI, and route-coverage contract testing | | [Local Models & Hugging Face](subsystems/local-models.md) | On-demand downloading from Hugging Face Hub, disk caching in `assets/cache/transformers.js`, and proxy pre-warming | ### Guides Step-by-step instructions for common dev tasks. | Document | What it covers | | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- | | [Adding a Provider](guides/adding-a-provider.md) | How to add a new LLM provider end-to-end | | [Adding a Tool](guides/adding-a-tool.md) | How to add a new agent tool | | [Adding a Shell Command](guides/adding-a-shell-command.md) | How to hook into the JS shell emulator | | [Adding a UI Page](guides/adding-a-page.md) | How to add a new Web Component page/section | | [Adding a Channel](guides/adding-a-channel.md) | How to add a new messaging channel | | [Protocol-Agnostic Integrations](guides/protocol-agnostic-integrations.md) | Plugin architecture and onboarding for external integrations | | [Service Accounts & Credentials](guides/adding-service-accounts.md) | How to manage encrypted credentials for channels and services | | [Configuring Messaging Channels](guides/configuring-messaging-channels.md) | User guide for Telegram and iMessage setup | | [Server Development Configuration](guides/server-development-configuration.md) | CLI flags, CORS modes, host binding, port configuration, opt-in HTTPS/TLS, CSP report logging | | [Publishing to GitHub Pages](guides/publishing-to-github-pages.md) | Step-by-step setup for static publishing via GitHub Actions, CLI builds, and template repos | ### Decisions The _why_ behind key choices. | Document | Decision | | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | [Headless CLI Agent Participant](decisions/headless-cli-agent-participant.md) | Architecture, capability negotiation, and SQLite backend for server-side agent execution | | [Bundled TypeScript Architecture](decisions/bundled-typescript-architecture.md) | Rationale for the transition to Rolldown + TypeScript | | [Native Web Components and Signals](decisions/native-web-components-and-signals.md) | Why native standards for UI and reactivity | | [Worker-Isolated Agent Runtime](decisions/worker-isolated-agent-runtime.md) | Why the agent and VM run in dedicated workers | | [IndexedDB and OPFS Storage](decisions/indexeddb-and-opfs-storage.md) | Why IndexedDB and OPFS for persistent storage | | [Peer-to-Peer Protocol (A2A via AGUI)](decisions/peer-protocol-a2a-agui.md) | Architecture and constraints for inter-agent communication | | [Server A2A Protocol (HTTP Binding)](decisions/server-a2a-http-binding.md) | Server-to-server A2A v1.0 HTTP + JSON-RPC 2.0 communication, discovery, and streaming | --- ## How to use these docs **Building ShadowClaw?** Start with the [System Overview](architecture/overview.md), then dive into whatever subsystem you're touching. **Changing build/runtime behavior?** Cross-check the architecture docs with root-level [README](../README.md) so scripts, output paths, and runtime topology stay aligned. **Adding a feature?** Check the [Guides](#guides) section for step-by-step instructions. **Working on E2E coverage?** Use the test architecture guide in [e2e/README.md](../e2e/README.md) for fixtures, page objects, and interaction patterns. **Wondering why something is the way it is?** The [Decisions](#decisions) section has you covered. **AI agents working in this repo** should start with [AGENTS.md](../AGENTS.md) for conventions and guardrails, then come here for the deeper context. AGENTS.md is optimized for agent consumption; these docs are optimized for human understanding (though agents are welcome here too). ## Contributing to docs - Keep docs accurate — update them when the code changes. - Architecture docs describe _what is_ and _how it works_. - Guides describe _how to do things_. - Decision docs describe _why decisions were made_ and are append-only (supersede, don't edit). - For UI documentation, keep component organization guidance aligned with `src/components/common/` for shared primitives and `src/components/settings/` for settings feature components. Verify and document visual component states with co-located Storybook stories (`npm run storybook`). - Keep references in this index in sync with actual files under `docs/`, plus root-level `README.md` and `e2e/README.md` when behavior changes cross boundaries. - When adding or renaming docs pages, update `docs/README.md` and verify the relevant references in `AGENTS.md`. - Use Mermaid diagrams generously — they render on GitHub and in most editors.