# ericwang915/pythonclaw architecture

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

- Interactive diagram: https://gitdiagram.com/ericwang915/pythonclaw
- Repository: https://github.com/ericwang915/pythonclaw

## Overview

1. **What this repository is**
   PythonClaw is a Python agent platform packaged as a single CLI app plus a long-running daemon. It exposes the same agent through multiple front doors: interactive CLI, web dashboard, and messaging channels. The core logic is shared; only the interface layer changes.

2. **Top-level execution paths**
   The main entry points are `pythonclaw/main.py` for CLI commands, `daemon.py` for lifecycle management, `server.py` for the multi-channel runtime, and `web/app.py` for the dashboard. `pythonclaw/__main__.py` and `pythonclaw/main.py` make it runnable as an installed package.

3. **Core agent boundary**
   `pythonclaw/core/agent.py` is the central reasoning loop. It coordinates chat turns, tool use, memory retrieval, skill activation, and response generation. `persistent_agent.py` extends that behavior with durable state across sessions.

4. **LLM provider abstraction**
   `pythonclaw/core/llm/` contains provider adapters for Anthropic, Gemini, and OpenAI-compatible APIs, plus shared response/base types. This layer isolates vendor-specific API details from the rest of the agent, so the rest of the system talks to a common interface.

5. **Memory and session state**
   `pythonclaw/core/memory/` and `session_store.py` implement persistent markdown-based memory and session tracking. The README indicates runtime state lives under `~/.pythonclaw/context/`, including curated memory and daily logs. This is a major persistence boundary distinct from ephemeral chat context.

6. **Session isolation and concurrency**
   `session_manager.py`, `core/session_store.py`, and the config flag for per-group isolation show that the system can segment state by chat/session identity. The README also calls out per-session locks and a global semaphore, so concurrency is controlled centrally to prevent interleaved agent actions.

7. **Retrieval / RAG subsystem**
   `core/knowledge/rag.py` and `core/retrieval/` implement the hybrid retrieval pipeline: chunking, sparse BM25 search, dense embedding retrieval, score fusion, and reranking. This subsystem sits between user query and the LLM, supplying relevant context before generation.

8. **Skill system as a separate content layer**
   `core/skill_loader.py` and `core/skillhub.py` manage the three-tier skill model: metadata, instructions, and bundled resources. Built-in skills live under `templates/skills/`, while marketplace skills are fetched from ClawHub. Skills are therefore both local assets and remotely installable extensions.

9. **Tools and controlled execution**
   `core/tools.py` is the tool boundary between model reasoning and side effects. The templates show concrete tool implementations for email, Slack, HTTP, code execution, PDF processing, scraping, and more. This means the agent can call local scripts and external APIs, but through a structured tool interface rather than arbitrary direct execution.

10. **Channel adapters**
    `channels/telegram_bot.py`, `channels/discord_bot.py`, and `channels/whatsapp_bot.py` are thin ingress/egress adapters. They translate platform-specific messages into agent sessions and send responses back out, while keeping the core agent and memory model channel-agnostic.

11. **Web dashboard**
    `web/app.py` and `web/static/index.html` provide a browser UI for chat, configuration, skill browsing, and identity editing. The dashboard is not the core runtime; it is another client of the same backend, with extra support for voice input via Deepgram STT and marketplace actions.

12. **Daemon and scheduling**
    `daemon.py`, `server.py`, and `scheduler/cron.py` / `scheduler/heartbeat.py` give the system background-process behavior and timed actions. The daemon is PID-managed and can run continuously, while the scheduler injects time-based jobs into the same agent runtime.

13. **Identity and personalization boundaries**
    The template structure under `templates/persona/`, `templates/soul/`, and the system skills for persona/soul changes show a separation between stable identity and swappable presentation/behavior. That is a distinct architectural layer from memory: identity files define “who the agent is,” while memory stores “what it remembers.”

14. **Configuration and external integrations**
    Configuration is driven by `pythonclaw.example.json` / `pythonclaw.json`, with environment-variable overrides. External boundaries that materially affect the architecture include LLM vendors, ClawHub for skill distribution, Deepgram for voice input, and channel APIs for Telegram/Discord/WhatsApp. The config also controls web hosting, concurrency, and per-group isolation, so runtime behavior is mostly declarative.

Main entry points: [`pythonclaw/core/agent.py`](https://github.com/ericwang915/pythonclaw/blob/main/pythonclaw/core/agent.py) (Agent loop), [`pythonclaw/config.py`](https://github.com/ericwang915/pythonclaw/blob/main/pythonclaw/config.py) (Config), [`pythonclaw/server.py`](https://github.com/ericwang915/pythonclaw/blob/main/pythonclaw/server.py) (Server), [`pythonclaw/core/skillhub.py`](https://github.com/ericwang915/pythonclaw/blob/main/pythonclaw/core/skillhub.py) (Skill hub)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_entry["Entrypoints"]
  node_n_main["CLI main<br/>entrypoint<br/>[main.py]"]
  node_n_module["Module entry<br/>entrypoint<br/>[__main__.py]"]
  node_n_daemon["Daemon<br/>runtime host<br/>[daemon.py]"]
  node_n_server["Server<br/>multi-channel host<br/>[server.py]"]
  node_n_sched["Scheduler<br/>timed jobs"]
  node_n_config["Config<br/>[config.py]"]
end

subgraph group_grp_core["Core runtime"]
  node_n_agent(("Agent loop<br/>core orchestrator<br/>[agent.py]"))
  node_n_pagent(("Persistent agent<br/>stateful agent"))
  node_n_session[("Session state<br/>session store<br/>[session_store.py]")]
  node_n_manager["Session manager<br/>concurrency control<br/>[session_manager.py]"]
  node_n_memory[("Memory store<br/>persistent memory")]
  node_n_rag["Retrieval pipeline<br/>hybrid retrieval"]
  node_n_knowledge["RAG glue<br/>knowledge integration<br/>[rag.py]"]
  node_n_llm["LLM adapters<br/>provider abstraction"]
end

subgraph group_grp_front["Front doors"]
  node_n_webapp["Web app<br/>dashboard UI<br/>[app.py]"]
  node_n_channels["Chat adapters<br/>ingress/egress"]
end

subgraph group_grp_ext["Extensions"]
  node_n_tools{{"Tool boundary<br/>tool router<br/>[tools.py]"}}
  node_n_skillhub["Skill hub<br/>skill manager<br/>[skillhub.py]"]
  node_n_loader["Skill loader<br/>[skill_loader.py]"]
end

subgraph group_grp_tpl["Templates"]
  node_n_templates["Templates<br/>bundled assets"]
end

node_n_module -->|"launches"| node_n_main
node_n_main -->|"starts"| node_n_agent
node_n_daemon -->|"hosts"| node_n_server
node_n_server -->|"routes to"| node_n_agent
node_n_webapp -->|"calls"| node_n_agent
node_n_channels -->|"bridges"| node_n_agent
node_n_agent -->|"queries"| node_n_llm
node_n_agent -->|"executes"| node_n_tools
node_n_agent -->|"reads/writes"| node_n_memory
node_n_agent -->|"retrieves context"| node_n_knowledge
node_n_knowledge -->|"uses"| node_n_rag
node_n_agent -->|"activates"| node_n_skillhub
node_n_skillhub -->|"resolves"| node_n_loader
node_n_manager -->|"coordinates"| node_n_session
node_n_pagent -->|"persists"| node_n_session
node_n_sched -->|"injects jobs"| node_n_agent
node_n_config -->|"configures"| node_n_server
node_n_config -->|"controls isolation"| node_n_manager
node_n_templates -->|"seeds"| node_n_skillhub
node_n_templates -->|"defines identity"| node_n_pagent
node_n_webapp -->|"reads"| node_n_config

click node_n_main "https://github.com/ericwang915/pythonclaw/blob/main/pythonclaw/main.py"
click node_n_module "https://github.com/ericwang915/pythonclaw/blob/main/pythonclaw/__main__.py"
click node_n_daemon "https://github.com/ericwang915/pythonclaw/blob/main/pythonclaw/daemon.py"
click node_n_server "https://github.com/ericwang915/pythonclaw/blob/main/pythonclaw/server.py"
click node_n_webapp "https://github.com/ericwang915/pythonclaw/blob/main/pythonclaw/web/app.py"
click node_n_channels "https://github.com/ericwang915/pythonclaw/tree/main/pythonclaw/channels"
click node_n_agent "https://github.com/ericwang915/pythonclaw/blob/main/pythonclaw/core/agent.py"
click node_n_pagent "https://github.com/ericwang915/pythonclaw/blob/main/pythonclaw/core/persistent_agent.py"
click node_n_session "https://github.com/ericwang915/pythonclaw/blob/main/pythonclaw/core/session_store.py"
click node_n_manager "https://github.com/ericwang915/pythonclaw/blob/main/pythonclaw/session_manager.py"
click node_n_memory "https://github.com/ericwang915/pythonclaw/tree/main/pythonclaw/core/memory"
click node_n_rag "https://github.com/ericwang915/pythonclaw/tree/main/pythonclaw/core/retrieval"
click node_n_knowledge "https://github.com/ericwang915/pythonclaw/blob/main/pythonclaw/core/knowledge/rag.py"
click node_n_llm "https://github.com/ericwang915/pythonclaw/tree/main/pythonclaw/core/llm"
click node_n_tools "https://github.com/ericwang915/pythonclaw/blob/main/pythonclaw/core/tools.py"
click node_n_skillhub "https://github.com/ericwang915/pythonclaw/blob/main/pythonclaw/core/skillhub.py"
click node_n_loader "https://github.com/ericwang915/pythonclaw/blob/main/pythonclaw/core/skill_loader.py"
click node_n_sched "https://github.com/ericwang915/pythonclaw/tree/main/pythonclaw/scheduler"
click node_n_config "https://github.com/ericwang915/pythonclaw/blob/main/pythonclaw/config.py"
click node_n_templates "https://github.com/ericwang915/pythonclaw/tree/main/pythonclaw/templates"

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_main,node_n_module,node_n_daemon,node_n_server,node_n_sched,node_n_config toneBlue
class node_n_agent,node_n_pagent,node_n_session,node_n_manager,node_n_memory,node_n_rag,node_n_knowledge,node_n_llm toneAmber
class node_n_webapp,node_n_channels toneMint
class node_n_tools,node_n_skillhub,node_n_loader toneRose
class node_n_templates toneIndigo
```

## Components

### Entrypoints

Main ways the package starts and exposes runtime modes.

- [CLI main](https://github.com/ericwang915/pythonclaw/blob/main/pythonclaw/main.py): entrypoint · Package command entry and interactive CLI command handling. · `pythonclaw/main.py`
- [Module entry](https://github.com/ericwang915/pythonclaw/blob/main/pythonclaw/__main__.py): entrypoint · Installed-package launcher for python -m execution. · `pythonclaw/__main__.py`
- [Daemon](https://github.com/ericwang915/pythonclaw/blob/main/pythonclaw/daemon.py): runtime host · Long-running process and lifecycle manager. · `pythonclaw/daemon.py`
- [Server](https://github.com/ericwang915/pythonclaw/blob/main/pythonclaw/server.py): multi-channel host · Shared runtime for channel-based agent sessions. · `pythonclaw/server.py`
- [Scheduler](https://github.com/ericwang915/pythonclaw/tree/main/pythonclaw/scheduler): timed jobs · Cron and heartbeat jobs injected into the runtime. · `pythonclaw/scheduler`
- [Config](https://github.com/ericwang915/pythonclaw/blob/main/pythonclaw/config.py): runtime config · JSON and environment-driven configuration for behavior, hosting, and isolation. · `pythonclaw/config.py`

### Core runtime

Agent loop, state management, retrieval, and execution boundaries.

- [Agent loop](https://github.com/ericwang915/pythonclaw/blob/main/pythonclaw/core/agent.py): core orchestrator · Central reasoning loop coordinating turns, tools, memory, and responses. · `pythonclaw/core/agent.py`
- [Persistent agent](https://github.com/ericwang915/pythonclaw/blob/main/pythonclaw/core/persistent_agent.py): stateful agent · Agent variant with durable behavior across sessions. · `pythonclaw/core/persistent_agent.py`
- [Session state](https://github.com/ericwang915/pythonclaw/blob/main/pythonclaw/core/session_store.py): session store · Session identity, isolation, and persisted session records. · `pythonclaw/core/session_store.py`
- [Session manager](https://github.com/ericwang915/pythonclaw/blob/main/pythonclaw/session_manager.py): concurrency control · Coordinates per-session locks and isolation boundaries. · `pythonclaw/session_manager.py`
- [Memory store](https://github.com/ericwang915/pythonclaw/tree/main/pythonclaw/core/memory): persistent memory · Markdown-based memory management and storage. · `pythonclaw/core/memory`
- [Retrieval pipeline](https://github.com/ericwang915/pythonclaw/tree/main/pythonclaw/core/retrieval): hybrid retrieval · Chunking, sparse/dense retrieval, fusion, and reranking for context selection. · `pythonclaw/core/retrieval`
- [RAG glue](https://github.com/ericwang915/pythonclaw/blob/main/pythonclaw/core/knowledge/rag.py): knowledge integration · High-level retrieval integration between agent and retrieval subsystem. · `pythonclaw/core/knowledge/rag.py`
- [LLM adapters](https://github.com/ericwang915/pythonclaw/tree/main/pythonclaw/core/llm): provider abstraction · Shared interface over Anthropic, Gemini, and OpenAI-compatible providers. · `pythonclaw/core/llm`

### Front doors

Channel and web adapters that connect users to the shared agent.

- [Web app](https://github.com/ericwang915/pythonclaw/blob/main/pythonclaw/web/app.py): dashboard UI · Browser dashboard and web backend entry. · `pythonclaw/web/app.py`
- [Chat adapters](https://github.com/ericwang915/pythonclaw/tree/main/pythonclaw/channels): ingress/egress · Platform connectors for Telegram, Discord, and WhatsApp. · `pythonclaw/channels`

### Extensions

Skills and tools that extend agent capabilities.

- [Tool boundary](https://github.com/ericwang915/pythonclaw/blob/main/pythonclaw/core/tools.py): tool router · Controlled execution boundary for side effects and external actions. · `pythonclaw/core/tools.py`
- [Skill hub](https://github.com/ericwang915/pythonclaw/blob/main/pythonclaw/core/skillhub.py): skill manager · Loads skill metadata, instructions, and bundled resources. · `pythonclaw/core/skillhub.py`
- [Skill loader](https://github.com/ericwang915/pythonclaw/blob/main/pythonclaw/core/skill_loader.py): skill loader · Resolves and activates local and marketplace skills. · `pythonclaw/core/skill_loader.py`

### Templates

Bundled identity, soul, and skill templates used at runtime or onboarding.

- [Templates](https://github.com/ericwang915/pythonclaw/tree/main/pythonclaw/templates): bundled assets · Persona, soul, and skill templates shipped with the repo. · `pythonclaw/templates`

## Connections

- Module entry → CLI main: launches · Module entry delegates to the CLI entrypoint.
- CLI main → Agent loop: starts · CLI commands invoke the shared agent runtime.
- Daemon → Server: hosts · Daemon manages the long-running server lifecycle.
- Server → Agent loop: routes to · Channel sessions are handled by the shared agent.
- Web app → Agent loop: calls · Web dashboard uses the same backend agent logic.
- Chat adapters → Agent loop: bridges · Messaging adapters translate external events into agent sessions.
- Agent loop → LLM adapters: queries · Agent uses provider adapters for model calls.
- Agent loop → Tool boundary: executes · Tool use is mediated through the tool boundary.
- Agent loop → Memory store: reads/writes · Agent persists and retrieves long-term memory.
- Agent loop → RAG glue: retrieves context · Agent asks the knowledge layer for relevant context.
- RAG glue → Retrieval pipeline: uses · Knowledge layer delegates to the retrieval pipeline.
- Agent loop → Skill hub: activates · Agent loads skills as behavioral and capability extensions.
- Skill hub → Skill loader: resolves · Skill hub relies on loader logic to materialize skills.
- Session manager → Session state: coordinates · Session manager enforces isolation over stored session state.
- Persistent agent → Session state: persists · Persistent agent extends behavior across stored sessions.
- Scheduler → Agent loop: injects jobs · Scheduled tasks run through the same agent runtime.
- Config → Server: configures · Configuration controls hosting and runtime behavior.
- Config → Session manager: controls isolation · Configuration sets per-group and concurrency policies.
- Templates → Skill hub: seeds · Bundled skill templates initialize the skill layer.
- Templates → Persistent agent: defines identity · Persona and soul templates shape persistent agent identity.
- Web app → Config: reads · Dashboard behavior is driven by shared configuration.
