# j-mazz/qwenclaw architecture

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

- Interactive diagram: https://gitdiagram.com/j-mazz/qwenclaw
- Repository: https://github.com/j-mazz/qwenclaw

## Overview

QwenClaw is a local agent runtime and gateway, with CLI and Lit dashboard clients. The principal flow sends a user request through the WebSocket RPC gateway to the agent loop, which calls an inference provider and may orchestrate tools before returning streamed results. Sessions persist transcripts; context and semantic memory support continued work. Separate capabilities include HTTP control, channels, MCP, scheduled jobs, access control, and a Node plugin sidecar. Edges use README-documented relationships or shown source references; many implementation details were not sampled, so those links are omitted.

Main entry points: [`src/core/agent_loop.cpp`](https://github.com/j-mazz/qwenclaw/blob/main/src/core/agent_loop.cpp) (Agent loop), [`ui/src/ui/app.ts`](https://github.com/j-mazz/qwenclaw/blob/main/ui/src/ui/app.ts) (Lit dashboard), [`src/tools/tool_registry.cpp`](https://github.com/j-mazz/qwenclaw/blob/main/src/tools/tool_registry.cpp) (Tool orchestration), [`src/gateway/gateway_server.cpp`](https://github.com/j-mazz/qwenclaw/blob/main/src/gateway/gateway_server.cpp) (WebSocket RPC)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User interfaces"]
  node_cli["CLI commands<br/>[cli_manager.cpp]"]
  node_dashboard["Lit dashboard<br/>[app.ts]"]
end

subgraph group_gateway["Gateway services"]
  node_ws_gateway["WebSocket RPC<br/>[gateway_server.cpp]"]
  node_rpc_handlers["RPC handlers"]
  node_http_api["HTTP control API<br/>[api_routes.cpp]"]
end

subgraph group_runtime["Agent runtime"]
  node_agent["Agent loop<br/>[agent_loop.cpp]"]
  node_providers["Inference providers"]
  node_context["Context assembly<br/>[prompt_builder.cpp]"]
end

subgraph group_capabilities["Tools and integrations"]
  node_tools["Tool orchestration<br/>[tool_registry.cpp]"]
  node_browser["Browser control<br/>[browser_tool.cpp]"]
  node_mcp_client["MCP client<br/>[mcp_client.cpp]"]
  node_mcp_server["MCP server<br/>[mcp_server.cpp]"]
  node_channels["Channel adapters"]
  node_plugins["Plugin system<br/>[plugin_system.cpp]"]
  node_sidecar["Plugin sidecar<br/>[index.ts]"]
end

subgraph group_state_security["State and safeguards"]
  node_sessions[("Session persistence")]
  node_memory[("Semantic memory<br/>[memory_search.cpp]")]
  node_scheduler["Cron scheduler<br/>[cron_scheduler.cpp]"]
  node_security["Access controls<br/>[rbac.cpp]"]
end

node_user(("Operator"))
node_llm["LLM services"]
node_external_mcp["External MCP servers"]
node_channel_users(("Channel users"))

node_user -->|"issues commands"| node_cli
node_user -->|"uses dashboard"| node_dashboard
node_cli -->|"sends RPC"| node_ws_gateway
node_dashboard -->|"connects by WebSocket"| node_ws_gateway
node_dashboard -->|"uses control API"| node_http_api
node_ws_gateway -->|"dispatches requests"| node_rpc_handlers
node_rpc_handlers -->|"routes agent work"| node_agent
node_agent -->|"builds prompt"| node_context
node_agent -->|"requests inference"| node_providers
node_providers -->|"calls inference"| node_llm
node_agent -->|"invokes tools"| node_tools
node_tools -->|"offers browser tool"| node_browser
node_tools -->|"bridges MCP tools"| node_mcp_client
node_mcp_server -->|"exposes tools"| node_external_mcp
node_agent -->|"persists transcripts"| node_sessions
node_agent -->|"searches memory"| node_memory
node_agent -->|"checks permissions"| node_security
node_channel_users -->|"sends messages"| node_channels
node_channels -->|"routes messages"| node_agent
node_scheduler -->|"schedules tasks"| node_agent
node_plugins -->|"runs plugin runtime"| node_sidecar

click node_cli "https://github.com/j-mazz/qwenclaw/blob/main/src/cli/cli_manager.cpp"
click node_dashboard "https://github.com/j-mazz/qwenclaw/blob/main/ui/src/ui/app.ts"
click node_ws_gateway "https://github.com/j-mazz/qwenclaw/blob/main/src/gateway/gateway_server.cpp"
click node_rpc_handlers "https://github.com/j-mazz/qwenclaw/blob/main/src/gateway/rpc_handlers_core.cpp"
click node_http_api "https://github.com/j-mazz/qwenclaw/blob/main/src/web/api_routes.cpp"
click node_agent "https://github.com/j-mazz/qwenclaw/blob/main/src/core/agent_loop.cpp"
click node_providers "https://github.com/j-mazz/qwenclaw/blob/main/src/providers/provider_registry.cpp"
click node_context "https://github.com/j-mazz/qwenclaw/blob/main/src/core/prompt_builder.cpp"
click node_tools "https://github.com/j-mazz/qwenclaw/blob/main/src/tools/tool_registry.cpp"
click node_browser "https://github.com/j-mazz/qwenclaw/blob/main/src/tools/browser_tool.cpp"
click node_mcp_client "https://github.com/j-mazz/qwenclaw/blob/main/src/mcp/mcp_client.cpp"
click node_mcp_server "https://github.com/j-mazz/qwenclaw/blob/main/src/mcp/mcp_server.cpp"
click node_channels "https://github.com/j-mazz/qwenclaw/blob/main/src/channels/adapter_manager.cpp"
click node_plugins "https://github.com/j-mazz/qwenclaw/blob/main/src/plugins/plugin_system.cpp"
click node_sidecar "https://github.com/j-mazz/qwenclaw/blob/main/sidecar/src/index.ts"
click node_sessions "https://github.com/j-mazz/qwenclaw/blob/main/src/session/session_manager.cpp"
click node_memory "https://github.com/j-mazz/qwenclaw/blob/main/src/core/memory_search.cpp"
click node_scheduler "https://github.com/j-mazz/qwenclaw/blob/main/src/core/cron_scheduler.cpp"
click node_security "https://github.com/j-mazz/qwenclaw/blob/main/src/security/rbac.cpp"

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_dashboard,node_channel_users toneBlue
class node_ws_gateway,node_rpc_handlers,node_http_api toneAmber
class node_agent,node_providers,node_context,node_external_mcp toneMint
class node_tools,node_browser,node_mcp_client,node_mcp_server,node_channels,node_plugins,node_sidecar toneRose
class node_sessions,node_memory,node_scheduler,node_security,node_user,node_llm toneIndigo
```

## Components

### User interfaces

- [CLI commands](https://github.com/j-mazz/qwenclaw/blob/main/src/cli/cli_manager.cpp): `src/cli/cli_manager.cpp`
- [Lit dashboard](https://github.com/j-mazz/qwenclaw/blob/main/ui/src/ui/app.ts): `ui/src/ui/app.ts`

### Gateway services

- [WebSocket RPC](https://github.com/j-mazz/qwenclaw/blob/main/src/gateway/gateway_server.cpp): `src/gateway/gateway_server.cpp`
- [RPC handlers](https://github.com/j-mazz/qwenclaw/blob/main/src/gateway/rpc_handlers_core.cpp): `src/gateway/rpc_handlers_core.cpp`
- [HTTP control API](https://github.com/j-mazz/qwenclaw/blob/main/src/web/api_routes.cpp): `src/web/api_routes.cpp`

### Agent runtime

- [Agent loop](https://github.com/j-mazz/qwenclaw/blob/main/src/core/agent_loop.cpp): `src/core/agent_loop.cpp`
- [Inference providers](https://github.com/j-mazz/qwenclaw/blob/main/src/providers/provider_registry.cpp): `src/providers/provider_registry.cpp`
- [Context assembly](https://github.com/j-mazz/qwenclaw/blob/main/src/core/prompt_builder.cpp): `src/core/prompt_builder.cpp`

### Tools and integrations

- [Tool orchestration](https://github.com/j-mazz/qwenclaw/blob/main/src/tools/tool_registry.cpp): `src/tools/tool_registry.cpp`
- [Browser control](https://github.com/j-mazz/qwenclaw/blob/main/src/tools/browser_tool.cpp): `src/tools/browser_tool.cpp`
- [MCP client](https://github.com/j-mazz/qwenclaw/blob/main/src/mcp/mcp_client.cpp): `src/mcp/mcp_client.cpp`
- [MCP server](https://github.com/j-mazz/qwenclaw/blob/main/src/mcp/mcp_server.cpp): `src/mcp/mcp_server.cpp`
- [Channel adapters](https://github.com/j-mazz/qwenclaw/blob/main/src/channels/adapter_manager.cpp): `src/channels/adapter_manager.cpp`
- [Plugin system](https://github.com/j-mazz/qwenclaw/blob/main/src/plugins/plugin_system.cpp): `src/plugins/plugin_system.cpp`
- [Plugin sidecar](https://github.com/j-mazz/qwenclaw/blob/main/sidecar/src/index.ts): `sidecar/src/index.ts`

### State and safeguards

- [Session persistence](https://github.com/j-mazz/qwenclaw/blob/main/src/session/session_manager.cpp): `src/session/session_manager.cpp`
- [Semantic memory](https://github.com/j-mazz/qwenclaw/blob/main/src/core/memory_search.cpp): `src/core/memory_search.cpp`
- [Cron scheduler](https://github.com/j-mazz/qwenclaw/blob/main/src/core/cron_scheduler.cpp): `src/core/cron_scheduler.cpp`
- [Access controls](https://github.com/j-mazz/qwenclaw/blob/main/src/security/rbac.cpp): `src/security/rbac.cpp`

### Other components

- **Operator**
- **LLM services**
- **External MCP servers**
- **Channel users**

## Connections

- Operator → CLI commands: issues commands
- Operator → Lit dashboard: uses dashboard
- CLI commands → WebSocket RPC: sends RPC
- Lit dashboard → WebSocket RPC: connects by WebSocket
- Lit dashboard → HTTP control API: uses control API
- WebSocket RPC → RPC handlers: dispatches requests
- RPC handlers → Agent loop: routes agent work
- Agent loop → Context assembly: builds prompt
- Agent loop → Inference providers: requests inference
- Inference providers → LLM services: calls inference
- Agent loop → Tool orchestration: invokes tools
- Tool orchestration → Browser control: offers browser tool
- Tool orchestration → MCP client: bridges MCP tools
- MCP server → External MCP servers: exposes tools
- Agent loop → Session persistence: persists transcripts
- Agent loop → Semantic memory: searches memory
- Agent loop → Access controls: checks permissions
- Channel users → Channel adapters: sends messages
- Channel adapters → Agent loop: routes messages
- Cron scheduler → Agent loop: schedules tasks
- Plugin system → Plugin sidecar: runs plugin runtime
