stackblitz-labs/bolt.diy

There is no Planner sub-agent — Bolt uses a single-turn streaming LLM loop orchestrated from the server. The entry point is app/routes/api.chat.ts, the server-side action handler for /api/chat. The client (Chat.client.tsx) calls useChat from the @ai-sdk/react SDK which sends a POST to that route. On the server, chatAction creates a SwitchableStream and runs a createDataStream block with an execute callback (line 93). Inside that callback, it first processes MCP tool invocations with mcpService.processToolInvocations (line 103), then optionally runs createSummary (line 122) and selectContext (line 164) — two separate LLM calls that create a chat summary and choose relevant files. The main generation is streamText (line 311) which calls the Vercel AI SDK's streamText with model, system prompt, and messages. Tool calls are exposed to the LLM via mcpService.toolsWithoutExecute set as options.tools (line 214), with toolChoice: 'auto' and maxSteps configurable per request. When the LLM response hits finishReason === 'length', the loop constructs a new user message with CONTINUE_PROMPT and calls streamText again, up to MAX_RESPONSE_SEGMENTS = 2 times (lines 251-298). The client uses @ai-sdk/react's useChat which handles streaming state, abort via stop(), and renders tool-call annotations in the UI.

Context gathering is a multi-phase server-side process triggered on every request when contextOptimization is enabled. First, createSummary (app/lib/.server/llm/create-summary.ts) sends all processed messages to the LLM with a structured prompt requesting a summary in a defined template format (project overview, decisions, implementation status, etc.). The summary is stored as a chatSummary annotation on the data stream. Next, selectContext (app/lib/.server/llm/select-context.ts) retrieves all file paths from the project (filtered by an ignore-list similar to .gitignore via the ignore package), reads the current context buffer from annotations, and asks the LLM which files are relevant by outputting <updateContextBuffer> XML with <includeFile> / <excludeFile> tags. Only 5 files are selected at a time (line 170). The file content is read from the in-memory FileMap (populated by FilesStore from the WebContainer filesystem) and formatted as boltAction type="file" entries inside a boltArtifact wrapper via createFilesContext in app/lib/.server/llm/utils.ts. For long sessions, messageSliceId is set to messages.length - 3 (api.chat.ts line 106-107), keeping only the last 3 messages, while the summary carries forward the earlier history. The summary and code context are injected into the system prompt before the main LLM call. The system prompt builder getSystemPrompt includes environment constraints, database instructions, artifact formatting rules, and design guidance — all composed into a single system message.

Code edits use a structured XML artifact format parsed in real-time during streaming. The LLM emits <boltArtifact> containing <boltAction type="file"> tags with filePath attributes and full file content — Bolt does NOT use diffs or search/replace due to WebContainer limitations (the system prompt explicitly states this at prompts.ts line 36). The StreamingMessageParser (app/lib/runtime/message-parser.ts) incrementally parses the stream: when it sees <boltArtifact> it emits an onArtifactOpen callback (line 289), then for each <boltAction type="file"> it extracts the filePath and accumulates content until </boltAction> closes. On close, it calls onActionClose (line 165) which triggers the ActionRunner. The ActionRunner (app/lib/runtime/action-runner.ts) executes each action sequentially via #executeAction (line 150). For file actions, #runFileAction (line 310) uses WebContainer's filesystem: it resolves the relative path, creates parent folders via mkdir -p, and writes the full file content with webcontainer.fs.writeFile. The EnhancedStreamingMessageParser (app/lib/runtime/enhanced-message-parser.ts) adds a fallback: if the LLM output contains no boltArtifact tags at all, it scans markdown code blocks and wraps them into artifacts automatically using file-path heuristics. There is no git integration for undo — file history is saved separately via saveFileHistory (action-runner.ts line 359) which stores previous versions as JSON under .history/. Shell commands (type="shell") are executed via the terminal emulator, and type="start" launches dev servers. Validation includes pre-flight shell command checks (#validateShellCommand at line 577) that verify paths exist before rm/cd/cp/mv operations.

Code execution runs inside WebContainer, an in-browser sandboxed Node.js runtime that cannot access the host system, files, or network beyond what the browser permits. The WebContainer.boot() call at app/lib/webcontainer/index.ts line 26 uses coep: 'credentialless' for cross-origin embedding policy and manages execution through virtual filesystem and shell APIs. Shell commands are validated before execution in #validateShellCommand (action-runner.ts:577-670) — it intercepts rm commands to add -f flags when files don't exist, checks that cd targets exist (auto-creating them with mkdir -p), and verifies source files before cp/mv. Locked files are enforced at the prompt level: the system prompt lists locked files and instructs the LLM not to modify them (stream-text.ts lines 202-223). On the security side, app/lib/security.ts provides rate limiting per-IP (10 req/min for LLM, 100 for other API endpoints), security headers (CSP, X-Frame-Options, HSTS), and API key format validation. MCP tool execution requires user approval via TOOL_EXECUTION_APPROVAL: in mcpService.ts line 402, the tool's execute function only runs when the result equals 'Yes, approved.', and rejections return TOOL_EXECUTION_DENIED. The maxSteps parameter (default 5, from MCP store) limits the number of LLM reasoning steps. Network requests from within WebContainer are restricted by browser policies — the system prompt warns against native binaries and restricts package choices to JS-only implementations.

Bolt supports 20+ providers registered in app/lib/modules/llm/registry.ts. Only 4 are enabled by default via ENABLED_PROVIDERS in the manager (OpenRouter, Anthropic, OpenAI, Google), but all 22 registered providers (Anthropic, OpenAI, Google, Groq, Cohere, DeepSeek, HuggingFace, Mistral, Ollama, OpenRouter, LMStudio, AmazonBedrock, Perplexity, Together, xAI, Fireworks, Hyperbolic, Cerebras, GitHub, Moonshot, OpenAILike, Z-AI) can be enabled. Each provider extends BaseProvider (app/lib/modules/llm/base-provider.ts) which provides common infrastructure: getting base URL and API key from environment variables, cookie settings, or server env; Docker URL rewriting; and model caching with cache-key generation. The getModelInstance method creates an SDK model instance per provider — for example, AnthropicProvider uses createAnthropic() from @ai-sdk/anthropic, OllamaProvider uses createOllama() from ollama-ai-provider. Models can be static (hardcoded in the provider class, e.g., Anthropic's three fallback models) or dynamic (fetched at runtime via getDynamicModels — Ollama fetches from /api/tags, Anthropic from api.anthropic.com/v1/models). The LLMManager singleton (app/lib/modules/llm/manager.ts) orchestrates provider registration and model list updates. It caches dynamic models based on a cache key derived from API keys and settings. The Vercel AI SDK serves as the unified interface: streamText in the SDK handles streaming, tool calling, token counting, and error handling. Reasoning models (o1, o3, GPT-5) get special handling — they use maxCompletionTokens instead of maxTokens, and have unsupported parameters (temperature, topP, etc.) filtered out (stream-text.ts lines 240-280). Per-model prompt tuning is handled by the PromptLibrary which supports swapping system prompts (default, original, optimized). No cost tracking is implemented in this codebase.

The primary extension mechanism is MCP (Model Context Protocol) via MCPService (app/lib/services/mcpService.ts). Users configure MCP servers in the UI (stored in localStorage), supporting three transport types: stdio (local subprocess), sse (Server-Sent Events), and streamable-http. The MCPService validates configs with Zod schemas, creates clients via experimental_createMCPClient from the AI SDK, registers tools into a shared ToolSet, and handles tool call execution with user approval. Tools are exposed to the LLM through the streaming options as tools: mcpService.toolsWithoutExecute (with execute functions stripped), and actual execution happens via processToolInvocations (mcpService.ts:377). New LLM providers can be added by extending BaseProvider in app/lib/modules/llm/providers/ and registering in registry.ts — the LLMManager dynamically discovers them. The system prompt is customizable via PromptLibrary (app/lib/common/prompt-library.ts) which provides a plugin-like registry of prompt templates — users can select between default, original, or optimized prompts. The contextOptimization feature is toggleable per-chat. For rules/instructions files, Bolt does not support AGENTS.md or similar — the system prompt is hardcoded. The app runs as both a web app (Remix/Cloudflare) and an Electron desktop app (electron/ directory). The headless/SDK path is through Cloudflare Workers actions: the api.chat.ts route accepts POST requests with messages, files, and settings as JSON. WebContainer provides the sandboxed execution environment. Settings and provider configurations are stored in cookies (API keys) and localStorage (MCP config, provider settings). No plugin system or custom-tool registration API beyond MCP is provided.