# zgsm-ai/costrict architecture

> Architecture diagram of the GitHub repository zgsm-ai/costrict, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zgsm-ai/costrict
- Repository: https://github.com/zgsm-ai/costrict

## Overview

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: [`src/core/task/Task.ts`](https://github.com/zgsm-ai/costrict/blob/main/src/core/task/Task.ts) (Task engine), [`src/core/tools/BaseTool.ts`](https://github.com/zgsm-ai/costrict/blob/main/src/core/tools/BaseTool.ts) (Toolkit), [`src/services/code-index/orchestrator.ts`](https://github.com/zgsm-ai/costrict/blob/main/src/services/code-index/orchestrator.ts) (Code index), [`apps/cli/src/agent/index.ts`](https://github.com/zgsm-ai/costrict/blob/main/apps/cli/src/agent/index.ts) (CLI agent loop)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_runtimes["Local runtimes"]
  node_n_extension_entry["VS Code entry<br/>extension host entry<br/>[extension.ts]"]
  node_n_extension_activate["Activation layer<br/>activation wiring<br/>[index.ts]"]
  node_n_webview_bridge["Webview bridge<br/>webview runtime<br/>[ClineProvider.ts]"]
  node_n_cli_frontend["CLI client<br/>terminal frontend<br/>[index.ts]"]
  node_n_cli_agent["CLI agent loop<br/>session engine<br/>[index.ts]"]
end

subgraph group_group_ui["Web UIs"]
  node_n_webview_ui["Webview UI<br/>react frontend<br/>[App.tsx]"]
  node_n_marketing_site["Marketing site<br/>nextjs site<br/>[page.tsx]"]
  node_n_evals_dashboard["Evals dashboard<br/>nextjs service<br/>[page.tsx]"]
end

subgraph group_group_shared["Shared agent core"]
  node_n_task_engine["Task engine<br/>conversation state<br/>[Task.ts]"]
  node_n_prompt_builder["Prompt builder<br/>prompt assembly<br/>[system.ts]"]
  node_n_toolkit["Toolkit<br/>tool execution<br/>[BaseTool.ts]"]
  node_n_provider_layer["Provider layer<br/>llm abstraction<br/>[index.ts]"]
  node_n_transform_layer["Transform layer<br/>payload adapters<br/>[stream.ts]"]
  node_n_websocket_state["Message state<br/>message pipeline"]
end

subgraph group_group_services["Indexing and services"]
  node_n_code_index["Code index<br/>repo indexing<br/>[orchestrator.ts]"]
  node_n_tree_sitter["Tree-sitter<br/>parser boundary<br/>[index.ts]"]
  node_n_code_review["Code review<br/>review workflow"]
  node_n_mcp_service["MCP service<br/>tool gateway<br/>[McpHub.ts]"]
  node_n_marketplace["Marketplace<br/>content install"]
end

subgraph group_group_packages["Workspace packages"]
  node_n_cloud_pkg["Cloud package<br/>auth and telemetry<br/>[CloudService.ts]"]
  node_n_types_pkg["Type contracts<br/>shared contracts<br/>[index.ts]"]
  node_n_core_pkg["Core utils<br/>shared libs<br/>[index.ts]"]
  node_n_ipc_pkg["IPC layer<br/>local rpc<br/>[index.ts]"]
  node_n_telemetry_pkg["Telemetry<br/>analytics<br/>[index.ts]"]
end

subgraph group_group_platform["External systems"]
  node_n_model_apis(("Model APIs<br/>external llm services"))
  node_n_local_os(("Local OS<br/>execution environment"))
  node_n_backing_services(("Backends<br/>cloud infra"))
end

node_n_extension_entry -->|"boots"| node_n_extension_activate
node_n_extension_activate -->|"hosts UI"| node_n_webview_bridge
node_n_webview_bridge -->|"messages"| node_n_webview_ui
node_n_cli_frontend -->|"drives"| node_n_cli_agent
node_n_cli_agent -->|"runs"| node_n_task_engine
node_n_webview_ui -->|"submits tasks"| node_n_task_engine
node_n_task_engine -->|"assembles"| node_n_prompt_builder
node_n_task_engine -->|"invokes"| node_n_toolkit
node_n_task_engine -->|"requests LLM"| node_n_provider_layer
node_n_provider_layer -->|"adapts"| node_n_transform_layer
node_n_transform_layer -->|"calls"| node_n_model_apis
node_n_toolkit -->|"acts on"| node_n_local_os
node_n_toolkit -->|"accesses"| node_n_mcp_service
node_n_toolkit -->|"searches"| node_n_code_index
node_n_code_index -->|"parses"| node_n_tree_sitter
node_n_code_index -->|"stores index"| node_n_backing_services
node_n_code_review -->|"reviews with"| node_n_code_index
node_n_marketplace -->|"installs content"| node_n_prompt_builder
node_n_cloud_pkg -->|"syncs"| node_n_backing_services
node_n_types_pkg -->|"contracts"| node_n_extension_entry
node_n_core_pkg -->|"reuses"| node_n_cli_agent
node_n_core_pkg -->|"supports"| node_n_task_engine
node_n_ipc_pkg -->|"bridges"| node_n_cli_agent
node_n_telemetry_pkg -->|"reports"| node_n_backing_services
node_n_marketing_site -->|"publishes"| node_n_backing_services
node_n_evals_dashboard -->|"persists runs"| node_n_backing_services

click node_n_extension_entry "https://github.com/zgsm-ai/costrict/blob/main/src/extension.ts"
click node_n_extension_activate "https://github.com/zgsm-ai/costrict/blob/main/src/activate/index.ts"
click node_n_webview_bridge "https://github.com/zgsm-ai/costrict/blob/main/src/core/webview/ClineProvider.ts"
click node_n_cli_frontend "https://github.com/zgsm-ai/costrict/blob/main/apps/cli/src/index.ts"
click node_n_cli_agent "https://github.com/zgsm-ai/costrict/blob/main/apps/cli/src/agent/index.ts"
click node_n_webview_ui "https://github.com/zgsm-ai/costrict/blob/main/webview-ui/src/App.tsx"
click node_n_marketing_site "https://github.com/zgsm-ai/costrict/blob/main/apps/web-roo-code/src/app/page.tsx"
click node_n_evals_dashboard "https://github.com/zgsm-ai/costrict/blob/main/apps/web-evals/src/app/page.tsx"
click node_n_task_engine "https://github.com/zgsm-ai/costrict/blob/main/src/core/task/Task.ts"
click node_n_prompt_builder "https://github.com/zgsm-ai/costrict/blob/main/src/core/prompts/system.ts"
click node_n_toolkit "https://github.com/zgsm-ai/costrict/blob/main/src/core/tools/BaseTool.ts"
click node_n_provider_layer "https://github.com/zgsm-ai/costrict/blob/main/src/api/providers/index.ts"
click node_n_transform_layer "https://github.com/zgsm-ai/costrict/blob/main/src/api/transform/stream.ts"
click node_n_websocket_state "https://github.com/zgsm-ai/costrict/blob/main/src/core/message-queue/MessageQueueService.ts"
click node_n_code_index "https://github.com/zgsm-ai/costrict/blob/main/src/services/code-index/orchestrator.ts"
click node_n_tree_sitter "https://github.com/zgsm-ai/costrict/blob/main/src/services/tree-sitter/index.ts"
click node_n_code_review "https://github.com/zgsm-ai/costrict/blob/main/src/core/costrict/code-review/codeReviewService.ts"
click node_n_mcp_service "https://github.com/zgsm-ai/costrict/blob/main/src/services/mcp/McpHub.ts"
click node_n_marketplace "https://github.com/zgsm-ai/costrict/blob/main/src/services/marketplace/MarketplaceManager.ts"
click node_n_cloud_pkg "https://github.com/zgsm-ai/costrict/blob/main/packages/cloud/src/CloudService.ts"
click node_n_types_pkg "https://github.com/zgsm-ai/costrict/blob/main/packages/types/src/index.ts"
click node_n_core_pkg "https://github.com/zgsm-ai/costrict/blob/main/packages/core/src/index.ts"
click node_n_ipc_pkg "https://github.com/zgsm-ai/costrict/blob/main/packages/ipc/src/index.ts"
click node_n_telemetry_pkg "https://github.com/zgsm-ai/costrict/blob/main/packages/telemetry/src/index.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_extension_entry,node_n_extension_activate,node_n_webview_bridge,node_n_cli_frontend,node_n_cli_agent toneBlue
class node_n_webview_ui,node_n_marketing_site,node_n_evals_dashboard toneAmber
class node_n_task_engine,node_n_prompt_builder,node_n_toolkit,node_n_provider_layer,node_n_transform_layer,node_n_websocket_state toneMint
class node_n_code_index,node_n_tree_sitter,node_n_code_review,node_n_mcp_service,node_n_marketplace toneRose
class node_n_cloud_pkg,node_n_types_pkg,node_n_core_pkg,node_n_ipc_pkg,node_n_telemetry_pkg toneIndigo
class node_n_model_apis,node_n_local_os,node_n_backing_services toneTeal
```

## Components

### Local runtimes

Editor and terminal clients that run the agent locally.

- [VS Code entry](https://github.com/zgsm-ai/costrict/blob/main/src/extension.ts): extension host entry · Bootstraps the extension and binds activation to the rest of the editor runtime. · `src/extension.ts`
- [Activation layer](https://github.com/zgsm-ai/costrict/blob/main/src/activate/index.ts): activation wiring · Registers commands, code actions, URI/task handlers, and terminal hooks. · `src/activate/index.ts`
- [Webview bridge](https://github.com/zgsm-ai/costrict/blob/main/src/core/webview/ClineProvider.ts): webview runtime · Manages the extension-side provider and message bridge to the sandboxed UI. · `src/core/webview/ClineProvider.ts`
- [CLI client](https://github.com/zgsm-ai/costrict/blob/main/apps/cli/src/index.ts): terminal frontend · Terminal-first client with commands, agent state, output management, and JSON events. · `apps/cli/src/index.ts`
- [CLI agent loop](https://github.com/zgsm-ai/costrict/blob/main/apps/cli/src/agent/index.ts): session engine · 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](https://github.com/zgsm-ai/costrict/blob/main/webview-ui/src/App.tsx): react frontend · React/Vite sandbox rendering chat, settings, history, marketplace, MCP, code review, and worktrees. · `webview-ui/src/App.tsx`
- [Marketing site](https://github.com/zgsm-ai/costrict/blob/main/apps/web-roo-code/src/app/page.tsx): nextjs site · Public-facing site for docs, blog, legal pages, and evals presentation. · `apps/web-roo-code/src/app/page.tsx`
- [Evals dashboard](https://github.com/zgsm-ai/costrict/blob/main/apps/web-evals/src/app/page.tsx): nextjs service · 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](https://github.com/zgsm-ai/costrict/blob/main/src/core/task/Task.ts): conversation state · Owns task lifecycle, message queues, persistence, condensing, checkpoints, and resume/replay. · `src/core/task/Task.ts`
- [Prompt builder](https://github.com/zgsm-ai/costrict/blob/main/src/core/prompts/system.ts): prompt assembly · Composes system prompts, rules, modes, skills, context, and tool instructions. · `src/core/prompts/system.ts`
- [Toolkit](https://github.com/zgsm-ai/costrict/blob/main/src/core/tools/BaseTool.ts): tool execution · Implements file, search, patch, command, MCP, todo, mode, checkpoint, and task-spawn tools. · `src/core/tools/BaseTool.ts`
- [Provider layer](https://github.com/zgsm-ai/costrict/blob/main/src/api/providers/index.ts): llm abstraction · Normalizes many model backends and streaming formats behind one request/response contract. · `src/api/providers/index.ts`
- [Transform layer](https://github.com/zgsm-ai/costrict/blob/main/src/api/transform/stream.ts): payload adapters · Adapts provider-specific payloads, streaming, reasoning, caching, and response shapes. · `src/api/transform/stream.ts`
- [Message state](https://github.com/zgsm-ai/costrict/blob/main/src/core/message-queue/MessageQueueService.ts): message pipeline · 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](https://github.com/zgsm-ai/costrict/blob/main/src/services/code-index/orchestrator.ts): repo indexing · Scans files, parses languages, builds embeddings, and supports repository search and review. · `src/services/code-index/orchestrator.ts`
- [Tree-sitter](https://github.com/zgsm-ai/costrict/blob/main/src/services/tree-sitter/index.ts): parser boundary · Language parsing and source-definition extraction used by indexing and code review. · `src/services/tree-sitter/index.ts`
- [Code review](https://github.com/zgsm-ai/costrict/blob/main/src/core/costrict/code-review/codeReviewService.ts): review workflow · Turns indexed repository knowledge into review findings and workflow actions. · `src/core/costrict/code-review/codeReviewService.ts`
- [MCP service](https://github.com/zgsm-ai/costrict/blob/main/src/services/mcp/McpHub.ts): tool gateway · Manages MCP hubs, server lifecycle, resources, and tool access. · `src/services/mcp/McpHub.ts`
- [Marketplace](https://github.com/zgsm-ai/costrict/blob/main/src/services/marketplace/MarketplaceManager.ts): content install · 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](https://github.com/zgsm-ai/costrict/blob/main/packages/cloud/src/CloudService.ts): auth and telemetry · Shared cloud, auth, share, settings, and telemetry integration for hosted features. · `packages/cloud/src/CloudService.ts`
- [Type contracts](https://github.com/zgsm-ai/costrict/blob/main/packages/types/src/index.ts): shared contracts · Cross-app message, provider, task, tool, MCP, cloud, and telemetry schemas. · `packages/types/src/index.ts`
- [Core utils](https://github.com/zgsm-ai/costrict/blob/main/packages/core/src/index.ts): shared libs · Reusable task-history, worktree, message, and custom-tool helpers for multiple runtimes. · `packages/core/src/index.ts`
- [IPC layer](https://github.com/zgsm-ai/costrict/blob/main/packages/ipc/src/index.ts): local rpc · Client/server primitives used by local processes and extension-host bridges. · `packages/ipc/src/index.ts`
- [Telemetry](https://github.com/zgsm-ai/costrict/blob/main/packages/telemetry/src/index.ts): analytics · 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**: external llm services · OpenAI, Anthropic, Bedrock, Gemini, OpenRouter, Ollama, and other compatible endpoints.
- **Local OS**: execution environment · Workspace filesystem, terminal, Git, shell, and editor APIs where tools act.
- **Backends**: cloud infra · Redis, Postgres, Docker runners, and SSE-backed evaluation infrastructure.

## Connections

- 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.
