How zgsm-ai/costrict works
1. Monorepo shape
This is a TypeScript pnpm-workspace monorepo orchestrated with Turbo. The top-level code is split into editor/runtime apps, web apps, and reusable packages, with a large amount of shared domain logic extracted into packages/* and src/* support modules.
2. Primary product surface: VS Code extension
The main runtime is the extension under src/. It boots through src/extension.ts and the src/activate/* layer, which registers commands, code actions, terminal hooks, and URI/task handlers. This is the boundary that connects VS Code’s extension host to the rest of the system.
3. Agent loop / chat workflow
The core user flow is: user input enters the webview UI, the extension builds a prompt and tool list, sends that to an LLM provider, then streams back assistant text plus tool calls. Tool results are executed locally and fed back into the same conversation/task state, with task history persisted for resume and replay.
4. Webview UI boundary
webview-ui/ is a separate React/Vite frontend running inside the extension webview sandbox. It renders the chat, settings, history, marketplace, MCP, code-review, modes, worktrees, and welcome screens, and communicates with the extension through message passing rather than direct filesystem or process access.
5. Tooling and action execution
The tool layer is centered in src/core/tools and src/core/prompts/tools/native-tools. It covers file operations, search, patch/apply-diff, command execution, image generation, task spawning, follow-up questions, todo updates, mode switching, MCP access, and checkpoints. These tools are guarded by auto-approval, permissions, and “human relay” flows where needed.
6. Model/provider abstraction
src/api/providers/* and src/api/transform/* normalize many LLM backends into a common request/stream format. The repo explicitly supports providers such as OpenAI, Anthropic, Bedrock, Gemini, OpenRouter, Ollama, and other OpenAI-compatible/local endpoints, with additional transformation layers for streaming, reasoning, caching, and provider-specific payload shapes.
7. Context, prompts, and task state
Prompt assembly lives in src/core/prompts, with mode/rules/skills/context sections composed into the final system prompt. Task lifecycle, message queues, persistence, checkpoints, condensing, and context management are handled in src/core/task*, src/core/context*, src/core/message-*, and src/core/task-persistence, forming the stateful “conversation engine” behind the UI.
8. Repository understanding and code review
A separate subsystem handles repo-wide indexing and code review: src/services/code-index, src/core/costrict/code-review, src/services/tree-sitter, and related search/glob utilities. Files are scanned and parsed, embedded into a vector store, and then used for RAG-style search/review workflows surfaced in the webview code-review UI. Tree-sitter and language-specific parsers are a key architectural boundary here.
9. Persistence, workspace, and local OS integration
The extension stores credentials, settings, history, and task metadata through local storage and VS Code secret/global state abstractions. It also integrates with the workspace, terminal, Git, file system, and shell, so the local machine is both the execution environment and the main data plane for code changes.
10. CLI application
apps/cli/ is a separate terminal-first frontend that reuses the same core concepts: auth, session history, agent state, JSON events, and task execution. It has its own command layer (auth, run, list, upgrade, cancellation) and a streaming integration harness, so diagrammatically it should be shown as a sibling client to the core agent logic rather than just a wrapper around the extension UI.
11. Evals and cloud-style services
packages/evals/ plus apps/web-evals/ form an evaluation platform with a Next.js dashboard, API routes, SSE streams, and backing services such as Redis and Postgres; Dockerized runner/web images are included. This is a distinct subsystem for running and inspecting benchmark/task runs, not part of the normal editor chat loop.
12. Marketing/docs site and shared libraries
apps/web-roo-code/ is a separate Next.js marketing/site app with blog, legal, evals, SEO, and analytics providers; it is not in the agent execution path. Shared support libraries live in packages/types, packages/core, packages/cloud, packages/telemetry, packages/ipc, packages/logger, and packages/vscode-shim, which provide cross-app contracts, auth/cloud utilities, telemetry, IPC, and test doubles.
13. Important diagram boundary
The key architectural split to draw is between: local editor/CLI runtimes, the webview sandbox, shared agent/prompt/tool logic, and external services (LLM APIs, MCP servers, telemetry, and eval backends). Most user-visible features are just different frontends over the same underlying task/prompt/tool pipeline.
Main entry points: Task.ts Task engine · BaseTool.ts Toolkit · orchestrator.ts Code index · index.ts CLI agent loop
Components 27
Local runtimes
Editor and terminal clients that run the agent locally.
- VS Code entry · Bootstraps the extension and binds activation to the rest of the editor runtime.
src/extension.ts - Activation layer · Registers commands, code actions, URI/task handlers, and terminal hooks.
src/activate/index.ts - Webview bridge · Manages the extension-side provider and message bridge to the sandboxed UI.
src/core/webview/ClineProvider.ts - CLI client · Terminal-first client with commands, agent state, output management, and JSON events.
apps/cli/src/index.ts - CLI agent loop · Runs prompt assembly, state storage, message processing, and extension-host coordination.
apps/cli/src/agent/index.ts
Web UIs
Sandboxed browser frontends for chat, settings, and product pages.
- Webview UI · React/Vite sandbox rendering chat, settings, history, marketplace, MCP, code review, and worktrees.
webview-ui/src/App.tsx - Marketing site · Public-facing site for docs, blog, legal pages, and evals presentation.
apps/web-roo-code/src/app/page.tsx - Evals dashboard · Evaluation UI and API routes for runs, tasks, and live streaming.
apps/web-evals/src/app/page.tsx
Shared agent core
Prompting, task orchestration, tools, providers, and common contracts.
- Task engine · Owns task lifecycle, message queues, persistence, condensing, checkpoints, and resume/replay.
src/core/task/Task.ts - Prompt builder · Composes system prompts, rules, modes, skills, context, and tool instructions.
src/core/prompts/system.ts - Toolkit · Implements file, search, patch, command, MCP, todo, mode, checkpoint, and task-spawn tools.
src/core/tools/BaseTool.ts - Provider layer · Normalizes many model backends and streaming formats behind one request/response contract.
src/api/providers/index.ts - Transform layer · Adapts provider-specific payloads, streaming, reasoning, caching, and response shapes.
src/api/transform/stream.ts - Message state · Handles assistant/user message consolidation, queueing, and task-history persistence.
src/core/message-queue/MessageQueueService.ts
Indexing and services
Repository understanding, code review, checkpoints, search, MCP, and marketplace services.
- Code index · Scans files, parses languages, builds embeddings, and supports repository search and review.
src/services/code-index/orchestrator.ts - Tree-sitter · Language parsing and source-definition extraction used by indexing and code review.
src/services/tree-sitter/index.ts - Code review · Turns indexed repository knowledge into review findings and workflow actions.
src/core/costrict/code-review/codeReviewService.ts - MCP service · Manages MCP hubs, server lifecycle, resources, and tool access.
src/services/mcp/McpHub.ts - Marketplace · Loads, validates, and installs marketplace commands, skills, and prompt content.
src/services/marketplace/MarketplaceManager.ts
Workspace packages
Reusable libraries and cross-app contracts.
- Cloud package · Shared cloud, auth, share, settings, and telemetry integration for hosted features.
packages/cloud/src/CloudService.ts - Type contracts · Cross-app message, provider, task, tool, MCP, cloud, and telemetry schemas.
packages/types/src/index.ts - Core utils · Reusable task-history, worktree, message, and custom-tool helpers for multiple runtimes.
packages/core/src/index.ts - IPC layer · Client/server primitives used by local processes and extension-host bridges.
packages/ipc/src/index.ts - Telemetry · Shared telemetry clients and metric recorders used across apps and services.
packages/telemetry/src/index.ts
External systems
Model APIs, local OS, and backing cloud services.
- Model APIs · OpenAI, Anthropic, Bedrock, Gemini, OpenRouter, Ollama, and other compatible endpoints.
- Local OS · Workspace filesystem, terminal, Git, shell, and editor APIs where tools act.
- Backends · Redis, Postgres, Docker runners, and SSE-backed evaluation infrastructure.
Connections 26
- VS Code entry → Activation layer: boots · Extension startup flows into activation and command registration.
- Activation layer → Webview bridge: hosts UI · Activation creates and manages the extension-side webview provider.
- Webview bridge → Webview UI: messages · The bridge forwards state, commands, and events to the sandboxed React UI.
- CLI client → CLI agent loop: drives · Terminal commands and input are handled by the CLI agent loop.
- CLI agent loop → Task engine: runs · The CLI reuses the same task lifecycle and session state model.
- Webview UI → Task engine: submits tasks · Chat and task actions are translated into task-engine events.
- Task engine → Prompt builder: assembles · Task state is turned into the final system prompt and tool context.
- Task engine → Toolkit: invokes · The engine executes tools and feeds results back into conversation state.
- Task engine → Provider layer: requests LLM · Task execution sends prompts and streams to model providers.
- Provider layer → Transform layer: adapts · Provider-specific request and stream shapes are normalized by transforms.
- Transform layer → Model APIs: calls · Normalized requests are sent to external model endpoints.
- Toolkit → Local OS: acts on · Tools operate on workspace files, terminals, processes, and Git.
- Toolkit → MCP service: accesses · MCP tools and resources are delegated through the MCP service boundary.
- Toolkit → Code index: searches · Search and codebase-query tools use repository indexing services.
- Code index → Tree-sitter: parses · Indexing relies on Tree-sitter and language parsers for structure extraction.
- Code index → Backends: stores index · Embeddings and run data are persisted in backing infrastructure.
- Code review → Code index: reviews with · Review workflows consume indexed repository knowledge and search results.
- Marketplace → Prompt builder: installs content · Marketplace content contributes modes, prompts, and command assets.
- Cloud package → Backends: syncs · Cloud features use remote auth, sharing, and telemetry services.
- Type contracts → VS Code entry: contracts · Shared types define extension-facing messages and configuration shapes.
- Core utils → CLI agent loop: reuses · CLI state and history reuse common core helpers.
- Core utils → Task engine: supports · Core utilities back task history, worktrees, and custom tools.
- IPC layer → CLI agent loop: bridges · IPC primitives support local client/server coordination.
- Telemetry → Backends: reports · Telemetry clients emit metrics to hosted analytics backends.
- Marketing site → Backends: publishes · The public site integrates with analytics and content delivery services.
- Evals dashboard → Backends: persists runs · The evals app stores and streams evaluation data through Redis and Postgres.