# agentscope-ai/copaw architecture

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

- Interactive diagram: https://gitdiagram.com/agentscope-ai/copaw
- Repository: https://github.com/agentscope-ai/copaw

## Overview

1. **Project shape**
   CoPaw is a Python-first assistant platform with three major faces: a backend runtime under `src/copaw`, a React/Vite web console in `console/`, and a documentation site in `website/`. The backend is the product core; the frontend and docs are separate build targets that get packaged alongside it.

2. **Entry points and process model**
   The main user-facing entry points are the CLI (`src/copaw/cli`) and the app/server runtime (`src/copaw/app`). The CLI covers install/init/admin workflows, while the app runtime starts the API, background services, channel integrations, and agent execution. Docker and desktop packaging wrap the same backend runtime for different deployment modes.

3. **API boundary**
   `src/copaw/app/routers` is the HTTP API surface consumed by the console. It exposes domains such as agents, auth, settings, files, workspace, skills, tools, providers, local models, token usage, voice, and chat/messages. The frontend’s `console/src/api/*` mirrors these routes, so the console is a thin client over the backend rather than an independent stateful app.

4. **Agent execution core**
   The `src/copaw/agents` package contains the reasoning and execution layer: agent prompts, model selection, routing/chat model logic, memory managers, skills loading, schema definitions, and tool dispatch. This is where user requests are turned into agent actions, tool calls, and responses. `react_agent.py` and related modules suggest a tool-using, iterative agent loop at the center of the runtime.

5. **Models and provider abstraction**
   `src/copaw/providers` abstracts LLM backends across cloud and local runtimes. It includes provider-specific adapters for OpenAI, Anthropic, Gemini, and Ollama, plus compatibility wrappers, retries, rate limiting, and multimodal probing. `src/copaw/local_models` handles local model download and execution via llama.cpp-style workflows, giving the system a no-API-key deployment path.

6. **Skills as the main extension mechanism**
   Skills live under `src/copaw/agents/skills` as markdown-defined capabilities, often with scripts, schemas, or reference assets alongside them. The platform supports built-in skills, hub/import flows, and skill pool management in both backend and console. This is a major boundary: the assistant’s capabilities are expanded by loading skills, not by hardcoding every behavior into the agent core.

7. **Tooling and side-effect boundaries**
   Tool execution is isolated in `src/copaw/agents/tools`. The tool set covers file I/O, shell, browser control, screenshots, media viewing, file search, memory search, time, token usage, and file sending. This layer is the main bridge from language-model decisions into real-world side effects on the local machine or workspace.

8. **Channels and multi-channel ingress**
   `src/copaw/app/channels` normalizes external message sources into one internal conversation model. It supports the built-in console channel plus third-party integrations such as DingTalk, Feishu, WeCom, WeChat, QQ, Telegram, Discord, Matrix, Mattermost, MQTT, iMessage, voice, and others. The channel manager/registry/renderer layers are the boundary between platform-specific messaging APIs and CoPaw’s shared agent runtime.

9. **State, workspace, and persistence**
   Local state is organized around the working directory, env store, workspace services, agent context, and JSON-backed repositories. Configuration and secrets are kept separate, and the README/Docker setup emphasizes persistent volumes for working data versus secrets. This is the main data persistence boundary: configuration, memory, skills, and workspace artifacts are stored locally and reused across restarts.

10. **Scheduling, background work, and multi-agent coordination**
    `src/copaw/app/crons` manages scheduled jobs and heartbeats, while `src/copaw/app/runner` handles background task execution, command dispatch, and task tracking. `src/copaw/app/multi_agent_manager.py` and related code support multiple agents running independently and collaborating. These subsystems turn CoPaw from a single chat loop into a long-running orchestration system.

11. **Security gates**
    CoPaw adds security at multiple layers: `security/tool_guard` blocks dangerous shell/file operations, `security/skill_scanner` scans skills for risky patterns, and `app/approvals` provides an approval flow. Security is not centralized in one place; instead, it guards the main effectful boundaries where skills, tools, and file access can impact the host system.

12. **Frontend and docs packaging**
    The `console/` app is a TypeScript/React UI for chat, settings, agent configuration, models, skills, channels, workspace, and token usage. The `website/` app is a separate public documentation/marketing site with static docs, release notes, and search. In packaging terms, the console is built and copied into the Python package, while the website is deployed independently.

13. **Deployment/runtime surfaces**
    The repo supports pip install, Docker, desktop packaging, and hosted deployment. `deploy/` contains container entrypoints and supervisord setup, `scripts/` contains build/install/release helpers, and GitHub Actions automate testing, PyPI publishing, Docker releases, and website deployment. A `tunnel/` package exists for connectivity/relay scenarios, indicating optional external network exposure.

14. **Primary end-to-end flow**
    A typical flow is: user enters through the console or a chat channel → backend router/channel normalizes the request → agent runtime selects a model/provider and loads context/skills → tools execute against local resources or external services → results are persisted in workspace/memory and returned to the channel/UI. That loop, plus the security gates and background schedulers, is the core architecture to diagram.

Main entry points: [`src/copaw/app`](https://github.com/agentscope-ai/copaw/tree/main/src/copaw/app) (App runtime), [`src/copaw/agents`](https://github.com/agentscope-ai/copaw/tree/main/src/copaw/agents) (Agent core), [`.github/workflows`](https://github.com/agentscope-ai/copaw/blob/main/.github/workflows) (CI releases), [`src/copaw/security`](https://github.com/agentscope-ai/copaw/tree/main/src/copaw/security) (Security gates)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Python backend"]
  node_cli["CLI<br/>entrypoint"]
  node_app_runtime["App runtime"]
  node_api_routers["HTTP API<br/>api surface"]
  node_channels["Channels<br/>ingress adapters"]
  node_agents_core["Agent core<br/>reasoning engine"]
  node_skills["Skills<br/>extension system"]
  node_tools["Tools<br/>effectors"]
  node_providers["Providers<br/>llm abstraction"]
  node_local_models["Local models<br/>model runtime"]
  node_workspace_state[("Workspace state<br/>persistence")]
  node_runner_crons["Runner + crons<br/>orchestration"]
  node_multi_agent(("Multi-agent<br/>coordination"))
  node_security{{"Security gates<br/>policy layer"}}
end

subgraph group_console["Web console"]
  node_console_app["Console UI<br/>react app"]
  node_console_api["Console API client<br/>typed client"]
end

subgraph group_website["Docs site"]
  node_website_app["Docs site"]
end

subgraph group_delivery["Packaging"]
  node_docker_packaging["Docker<br/>deployment"]
  node_desktop_packaging["Desktop packaging"]
  node_ci_release["CI releases<br/>automation<br/>[workflows]"]
end

node_cli -->|"starts"| node_app_runtime
node_app_runtime -->|"serves"| node_api_routers
node_app_runtime -->|"hosts"| node_channels
node_app_runtime -->|"executes"| node_agents_core
node_agents_core -->|"loads"| node_skills
node_agents_core -->|"invokes"| node_tools
node_agents_core -->|"selects models"| node_providers
node_providers -->|"falls back to"| node_local_models
node_app_runtime -->|"persists to"| node_workspace_state
node_runner_crons -->|"triggers"| node_agents_core
node_multi_agent -->|"coordinates"| node_agents_core
node_security -->|"guards"| node_tools
node_security -->|"scans"| node_skills
node_console_app -->|"calls"| node_console_api
node_console_api -->|"consumes"| node_api_routers
node_website_app -->|"deployed by"| node_ci_release
node_docker_packaging -->|"wraps"| node_app_runtime
node_desktop_packaging -->|"bundles"| node_app_runtime
node_ci_release -->|"builds"| node_console_app
node_ci_release -->|"publishes"| node_docker_packaging
node_ci_release -->|"packages"| node_desktop_packaging
node_ci_release -->|"deploys"| node_website_app

click node_cli "https://github.com/agentscope-ai/copaw/tree/main/src/copaw/cli"
click node_app_runtime "https://github.com/agentscope-ai/copaw/tree/main/src/copaw/app"
click node_api_routers "https://github.com/agentscope-ai/copaw/tree/main/src/copaw/app/routers"
click node_channels "https://github.com/agentscope-ai/copaw/tree/main/src/copaw/app/channels"
click node_agents_core "https://github.com/agentscope-ai/copaw/tree/main/src/copaw/agents"
click node_skills "https://github.com/agentscope-ai/copaw/tree/main/src/copaw/agents/skills"
click node_tools "https://github.com/agentscope-ai/copaw/tree/main/src/copaw/agents/tools"
click node_providers "https://github.com/agentscope-ai/copaw/tree/main/src/copaw/providers"
click node_local_models "https://github.com/agentscope-ai/copaw/tree/main/src/copaw/local_models"
click node_workspace_state "https://github.com/agentscope-ai/copaw/tree/main/src/copaw/app/workspace"
click node_runner_crons "https://github.com/agentscope-ai/copaw/tree/main/src/copaw/app/runner"
click node_multi_agent "https://github.com/agentscope-ai/copaw/blob/main/src/copaw/app/multi_agent_manager.py"
click node_security "https://github.com/agentscope-ai/copaw/tree/main/src/copaw/security"
click node_console_app "https://github.com/agentscope-ai/copaw/tree/main/console/src"
click node_console_api "https://github.com/agentscope-ai/copaw/tree/main/console/src/api"
click node_website_app "https://github.com/agentscope-ai/copaw/tree/main/website/src"
click node_docker_packaging "https://github.com/agentscope-ai/copaw/tree/main/deploy"
click node_desktop_packaging "https://github.com/agentscope-ai/copaw/tree/main/scripts/pack"
click node_ci_release "https://github.com/agentscope-ai/copaw/blob/main/.github/workflows"

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_cli,node_app_runtime,node_api_routers,node_channels,node_agents_core,node_skills,node_tools,node_providers,node_local_models,node_workspace_state,node_runner_crons,node_multi_agent,node_security toneBlue
class node_console_app,node_console_api toneAmber
class node_website_app toneMint
class node_docker_packaging,node_desktop_packaging,node_ci_release toneRose
```

## Components

### Python backend

Core runtime, CLI, APIs, agents, providers, security, and persistence.

- [CLI](https://github.com/agentscope-ai/copaw/tree/main/src/copaw/cli): entrypoint · Install, init, auth, daemon, and admin workflows. · `src/copaw/cli`
- [App runtime](https://github.com/agentscope-ai/copaw/tree/main/src/copaw/app): runtime · Starts API, channels, background work, and agent execution. · `src/copaw/app`
- [HTTP API](https://github.com/agentscope-ai/copaw/tree/main/src/copaw/app/routers): api surface · Backend routers consumed by the console and external clients. · `src/copaw/app/routers`
- [Channels](https://github.com/agentscope-ai/copaw/tree/main/src/copaw/app/channels): ingress adapters · Normalizes console and third-party messaging platforms into conversations. · `src/copaw/app/channels`
- [Agent core](https://github.com/agentscope-ai/copaw/tree/main/src/copaw/agents): reasoning engine · Prompts, routing, memory, skill loading, and tool dispatch. · `src/copaw/agents`
- [Skills](https://github.com/agentscope-ai/copaw/tree/main/src/copaw/agents/skills): extension system · Markdown-defined capabilities and packaged scripts/reference assets. · `src/copaw/agents/skills`
- [Tools](https://github.com/agentscope-ai/copaw/tree/main/src/copaw/agents/tools): effectors · File, shell, browser, media, search, memory, and token-usage actions. · `src/copaw/agents/tools`
- [Providers](https://github.com/agentscope-ai/copaw/tree/main/src/copaw/providers): llm abstraction · Cloud and local model adapters with retries, limits, and probing. · `src/copaw/providers`
- [Local models](https://github.com/agentscope-ai/copaw/tree/main/src/copaw/local_models): model runtime · Downloads and runs local models for no-key deployments. · `src/copaw/local_models`
- [Workspace state](https://github.com/agentscope-ai/copaw/tree/main/src/copaw/app/workspace): persistence · Configuration, env store, workspace services, and local data reuse. · `src/copaw/app/workspace`
- [Runner + crons](https://github.com/agentscope-ai/copaw/tree/main/src/copaw/app/runner): orchestration · Background task execution, scheduling, heartbeats, and task tracking. · `src/copaw/app/runner`
- [Multi-agent](https://github.com/agentscope-ai/copaw/blob/main/src/copaw/app/multi_agent_manager.py): coordination · Coordinates multiple agents and independent sessions. · `src/copaw/app/multi_agent_manager.py`
- [Security gates](https://github.com/agentscope-ai/copaw/tree/main/src/copaw/security): policy layer · Tool guard, skill scanning, and approval flow around effectful actions. · `src/copaw/security`

### Web console

React/Vite UI used as a thin client over backend routers.

- [Console UI](https://github.com/agentscope-ai/copaw/tree/main/console/src): react app · Chat, settings, skills, models, channels, workspace, and usage screens. · `console/src`
- [Console API client](https://github.com/agentscope-ai/copaw/tree/main/console/src/api): typed client · Mirrors backend routers and powers the UI data flows. · `console/src/api`

### Docs site

Public documentation and marketing site.

- [Docs site](https://github.com/agentscope-ai/copaw/tree/main/website/src): site · Public docs, release notes, search, and marketing pages. · `website/src`

### Packaging

Docker, desktop, scripts, and CI/CD release surfaces.

- [Docker](https://github.com/agentscope-ai/copaw/tree/main/deploy): deployment · Container entrypoints and supervisord wrapping the backend runtime. · `deploy`
- [Desktop packaging](https://github.com/agentscope-ai/copaw/tree/main/scripts/pack): packaging · Desktop build and bundle scripts for shipped installs. · `scripts/pack`
- [CI releases](https://github.com/agentscope-ai/copaw/blob/main/.github/workflows): automation · Build, test, publish, and website deployment workflows. · `.github/workflows`

## Connections

- CLI → App runtime: starts · CLI launches or manages the backend runtime.
- App runtime → HTTP API: serves · Runtime exposes HTTP routes for console and integrations.
- App runtime → Channels: hosts · Runtime runs channel adapters and queueing.
- App runtime → Agent core: executes · Runtime hands normalized messages to the agent loop.
- Agent core → Skills: loads · Agent core discovers and uses skills as capabilities.
- Agent core → Tools: invokes · Agent decisions dispatch into effectful tools.
- Agent core → Providers: selects models · Routing and model selection go through provider abstraction.
- Providers → Local models: falls back to · Provider layer can route to local model runtime.
- App runtime → Workspace state: persists to · Runtime stores config, workspace, and local state.
- Runner + crons → Agent core: triggers · Background tasks can start or resume agent work.
- Multi-agent → Agent core: coordinates · Multiple agents share the same execution core.
- Security gates → Tools: guards · Tool execution is filtered through policy and approvals.
- Security gates → Skills: scans · Skills are checked for risky patterns before use.
- Console UI → Console API client: calls · UI uses typed API modules as its backend client.
- Console API client → HTTP API: consumes · Console client mirrors backend route domains.
- Docs site → CI releases: deployed by · Docs site has its own build and deployment path.
- Docker → App runtime: wraps · Container image packages the same backend runtime.
- Desktop packaging → App runtime: bundles · Desktop packaging ships the backend runtime with assets.
- CI releases → Console UI: builds · CI validates and builds the console frontend.
- CI releases → Docker: publishes · CI produces Docker release artifacts.
- CI releases → Desktop packaging: packages · CI builds desktop distribution artifacts.
- CI releases → Docs site: deploys · CI deploys the public website.
