# zoo-code-org/zoo-code architecture

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

- Interactive diagram: https://gitdiagram.com/zoo-code-org/zoo-code
- Repository: https://github.com/zoo-code-org/zoo-code

## Overview

Zoo Code is a VS Code AI coding assistant: users submit coding or question tasks, choose a mode and model, and receive streamed answers or tool-driven workspace changes. The main product path spans the extension UI, task orchestration, provider adapters, and editor/workspace capabilities. Separate branches cover codebase search, skills and modes, marketplace extensions, MCP connections, cloud services, and the standalone CLI. Several links are documented or inferred from the product description because the task and webview orchestration sources were not sampled; those links are marked unverified.

Main entry points: [`src/core/webview/ClineProvider.ts`](https://github.com/zoo-code-org/zoo-code/blob/main/src/core/webview/ClineProvider.ts) (Task Orchestration), [`src/activate/index.ts`](https://github.com/zoo-code-org/zoo-code/blob/main/src/activate/index.ts) (VS Code Extension), [`src/api/providers/openrouter.ts`](https://github.com/zoo-code-org/zoo-code/blob/main/src/api/providers/openrouter.ts) (Provider Adapters), [`webview-ui/src/App.tsx`](https://github.com/zoo-code-org/zoo-code/blob/main/webview-ui/src/App.tsx) (Chat Webview)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User Interaction"]
  node_extension["VS Code Extension<br/>[index.ts]"]
  node_webview["Chat Webview<br/>[App.tsx]"]
  node_message_handler["Webview Messages"]
  node_cli_agent["CLI Agent<br/>[agent-state.ts]"]
end

subgraph group_task["Task Runtime"]
  node_task_engine["Task Orchestration<br/>[ClineProvider.ts]"]
  node_prompts["Prompt Assembly"]
  node_tool_calls["Assistant Tool Calls"]
  node_task_history[("Task History")]
end

subgraph group_models["Model Access"]
  node_provider_api["Provider API<br/>[index.ts]"]
  node_provider_adapters["Provider Adapters<br/>[openrouter.ts]"]
  node_model_catalog[("Model Catalog<br/>[modelCache.ts]")]
  node_stream_transforms["Stream Transforms<br/>[stream.ts]"]
end

subgraph group_workspace["Workspace Features"]
  node_code_search["Semantic Code Search<br/>[manager.ts]"]
  node_modes["Custom Modes"]
  node_skills["Skills<br/>[SkillsManager.ts]"]
  node_marketplace["Marketplace"]
end

subgraph group_integrations["Extensions &amp; Services"]
  node_mcp_auth["MCP OAuth"]
  node_cloud_auth["Cloud Sign-In<br/>[WebAuthService.ts]"]
end

node_developer(("Developer"))
node_llm_service{{"Model Service"}}
node_mcp_server{{"MCP Server"}}

node_developer -.->|"starts work"| node_extension
node_extension -.->|"opens chat"| node_webview
node_webview -.->|"sends messages"| node_message_handler
node_message_handler -.->|"dispatches task"| node_task_engine
node_task_engine -.->|"assembles prompt"| node_prompts
node_task_engine -.->|"requests completion"| node_provider_api
node_provider_api -->|"selects provider"| node_provider_adapters
node_provider_adapters -->|"loads models"| node_model_catalog
node_provider_adapters -->|"emits chunks"| node_stream_transforms
node_provider_adapters -.->|"calls model"| node_llm_service
node_task_engine -.->|"handles response"| node_tool_calls
node_tool_calls -.->|"requests actions"| node_task_engine
node_task_engine -.->|"persists task"| node_task_history
node_task_engine -.->|"searches codebase"| node_code_search
node_task_engine -.->|"applies mode"| node_modes
node_task_engine -.->|"uses skills"| node_skills
node_task_engine -.->|"authenticates MCP"| node_mcp_auth
node_mcp_auth -.->|"authorizes access"| node_mcp_server
node_extension -.->|"manages extensions"| node_marketplace
node_extension -.->|"signs in"| node_cloud_auth
node_developer -.->|"runs CLI"| node_cli_agent

click node_extension "https://github.com/zoo-code-org/zoo-code/blob/main/src/activate/index.ts"
click node_webview "https://github.com/zoo-code-org/zoo-code/blob/main/webview-ui/src/App.tsx"
click node_message_handler "https://github.com/zoo-code-org/zoo-code/blob/main/src/core/webview/webviewMessageHandler.ts"
click node_task_engine "https://github.com/zoo-code-org/zoo-code/blob/main/src/core/webview/ClineProvider.ts"
click node_prompts "https://github.com/zoo-code-org/zoo-code/blob/main/src/core/prompts/sections/custom-instructions.ts"
click node_tool_calls "https://github.com/zoo-code-org/zoo-code/blob/main/src/core/assistant-message/presentAssistantMessage.ts"
click node_task_history "https://github.com/zoo-code-org/zoo-code/blob/main/src/core/task-persistence/TaskHistoryStore.ts"
click node_provider_api "https://github.com/zoo-code-org/zoo-code/blob/main/src/api/index.ts"
click node_provider_adapters "https://github.com/zoo-code-org/zoo-code/blob/main/src/api/providers/openrouter.ts"
click node_model_catalog "https://github.com/zoo-code-org/zoo-code/blob/main/src/api/providers/fetchers/modelCache.ts"
click node_stream_transforms "https://github.com/zoo-code-org/zoo-code/blob/main/src/api/transform/stream.ts"
click node_code_search "https://github.com/zoo-code-org/zoo-code/blob/main/src/services/code-index/manager.ts"
click node_modes "https://github.com/zoo-code-org/zoo-code/blob/main/src/core/config/CustomModesManager.ts"
click node_skills "https://github.com/zoo-code-org/zoo-code/blob/main/src/services/skills/SkillsManager.ts"
click node_marketplace "https://github.com/zoo-code-org/zoo-code/blob/main/src/services/marketplace/MarketplaceManager.ts"
click node_mcp_auth "https://github.com/zoo-code-org/zoo-code/blob/main/src/services/mcp/McpOAuthClientProvider.ts"
click node_cloud_auth "https://github.com/zoo-code-org/zoo-code/blob/main/packages/cloud/src/WebAuthService.ts"
click node_cli_agent "https://github.com/zoo-code-org/zoo-code/blob/main/apps/cli/src/agent/agent-state.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_extension,node_webview,node_message_handler,node_cli_agent toneBlue
class node_task_engine,node_prompts,node_tool_calls,node_task_history toneAmber
class node_provider_api,node_provider_adapters,node_model_catalog,node_stream_transforms,node_mcp_server toneMint
class node_code_search,node_modes,node_skills,node_marketplace toneRose
class node_mcp_auth,node_cloud_auth,node_developer,node_llm_service toneIndigo
```

## Components

### User Interaction

- [VS Code Extension](https://github.com/zoo-code-org/zoo-code/blob/main/src/activate/index.ts): `src/activate/index.ts`
- [Chat Webview](https://github.com/zoo-code-org/zoo-code/blob/main/webview-ui/src/App.tsx): `webview-ui/src/App.tsx`
- [Webview Messages](https://github.com/zoo-code-org/zoo-code/blob/main/src/core/webview/webviewMessageHandler.ts): `src/core/webview/webviewMessageHandler.ts`
- [CLI Agent](https://github.com/zoo-code-org/zoo-code/blob/main/apps/cli/src/agent/agent-state.ts): `apps/cli/src/agent/agent-state.ts`

### Task Runtime

- [Task Orchestration](https://github.com/zoo-code-org/zoo-code/blob/main/src/core/webview/ClineProvider.ts): `src/core/webview/ClineProvider.ts`
- [Prompt Assembly](https://github.com/zoo-code-org/zoo-code/blob/main/src/core/prompts/sections/custom-instructions.ts): `src/core/prompts/sections/custom-instructions.ts`
- [Assistant Tool Calls](https://github.com/zoo-code-org/zoo-code/blob/main/src/core/assistant-message/presentAssistantMessage.ts): `src/core/assistant-message/presentAssistantMessage.ts`
- [Task History](https://github.com/zoo-code-org/zoo-code/blob/main/src/core/task-persistence/TaskHistoryStore.ts): `src/core/task-persistence/TaskHistoryStore.ts`

### Model Access

- [Provider API](https://github.com/zoo-code-org/zoo-code/blob/main/src/api/index.ts): `src/api/index.ts`
- [Provider Adapters](https://github.com/zoo-code-org/zoo-code/blob/main/src/api/providers/openrouter.ts): `src/api/providers/openrouter.ts`
- [Model Catalog](https://github.com/zoo-code-org/zoo-code/blob/main/src/api/providers/fetchers/modelCache.ts): `src/api/providers/fetchers/modelCache.ts`
- [Stream Transforms](https://github.com/zoo-code-org/zoo-code/blob/main/src/api/transform/stream.ts): `src/api/transform/stream.ts`

### Workspace Features

- [Semantic Code Search](https://github.com/zoo-code-org/zoo-code/blob/main/src/services/code-index/manager.ts): `src/services/code-index/manager.ts`
- [Custom Modes](https://github.com/zoo-code-org/zoo-code/blob/main/src/core/config/CustomModesManager.ts): `src/core/config/CustomModesManager.ts`
- [Skills](https://github.com/zoo-code-org/zoo-code/blob/main/src/services/skills/SkillsManager.ts): `src/services/skills/SkillsManager.ts`
- [Marketplace](https://github.com/zoo-code-org/zoo-code/blob/main/src/services/marketplace/MarketplaceManager.ts): `src/services/marketplace/MarketplaceManager.ts`

### Extensions & Services

- [MCP OAuth](https://github.com/zoo-code-org/zoo-code/blob/main/src/services/mcp/McpOAuthClientProvider.ts): `src/services/mcp/McpOAuthClientProvider.ts`
- [Cloud Sign-In](https://github.com/zoo-code-org/zoo-code/blob/main/packages/cloud/src/WebAuthService.ts): `packages/cloud/src/WebAuthService.ts`

### Other components

- **Developer**
- **Model Service**
- **MCP Server**

## Connections

- Developer → VS Code Extension: starts work (evidence: `README.md`)
- VS Code Extension → Chat Webview: opens chat
- Chat Webview → Webview Messages: sends messages
- Webview Messages → Task Orchestration: dispatches task
- Task Orchestration → Prompt Assembly: assembles prompt
- Task Orchestration → Provider API: requests completion
- Provider API → Provider Adapters: selects provider (evidence: `src/api/index.ts`)
- Provider Adapters → Model Catalog: loads models (evidence: `src/api/providers/openrouter.ts`)
- Provider Adapters → Stream Transforms: emits chunks (evidence: `src/api/providers/openrouter.ts`)
- Provider Adapters → Model Service: calls model (evidence: `README.md`)
- Task Orchestration → Assistant Tool Calls: handles response
- Assistant Tool Calls → Task Orchestration: requests actions
- Task Orchestration → Task History: persists task
- Task Orchestration → Semantic Code Search: searches codebase (evidence: `README.md`)
- Task Orchestration → Custom Modes: applies mode (evidence: `README.md`)
- Task Orchestration → Skills: uses skills (evidence: `README.md`)
- Task Orchestration → MCP OAuth: authenticates MCP
- MCP OAuth → MCP Server: authorizes access (evidence: `README.md`)
- VS Code Extension → Marketplace: manages extensions
- VS Code Extension → Cloud Sign-In: signs in
- Developer → CLI Agent: runs CLI
