How ericwang915/pythonclaw works
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: agent.py Agent loop · config.py Config · server.py Server · skillhub.py Skill hub
Components 20
Entrypoints
Main ways the package starts and exposes runtime modes.
- CLI main · Package command entry and interactive CLI command handling.
pythonclaw/main.py - Module entry · Installed-package launcher for python -m execution.
pythonclaw/__main__.py - Daemon · Long-running process and lifecycle manager.
pythonclaw/daemon.py - Server · Shared runtime for channel-based agent sessions.
pythonclaw/server.py - Scheduler · Cron and heartbeat jobs injected into the runtime.
pythonclaw/scheduler - 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 · Central reasoning loop coordinating turns, tools, memory, and responses.
pythonclaw/core/agent.py - Persistent agent · Agent variant with durable behavior across sessions.
pythonclaw/core/persistent_agent.py - Session state · Session identity, isolation, and persisted session records.
pythonclaw/core/session_store.py - Session manager · Coordinates per-session locks and isolation boundaries.
pythonclaw/session_manager.py - Memory store · Markdown-based memory management and storage.
pythonclaw/core/memory - Retrieval pipeline · Chunking, sparse/dense retrieval, fusion, and reranking for context selection.
pythonclaw/core/retrieval - RAG glue · High-level retrieval integration between agent and retrieval subsystem.
pythonclaw/core/knowledge/rag.py - LLM adapters · 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 · Browser dashboard and web backend entry.
pythonclaw/web/app.py - Chat adapters · Platform connectors for Telegram, Discord, and WhatsApp.
pythonclaw/channels
Extensions
Skills and tools that extend agent capabilities.
- Tool boundary · Controlled execution boundary for side effects and external actions.
pythonclaw/core/tools.py - Skill hub · Loads skill metadata, instructions, and bundled resources.
pythonclaw/core/skillhub.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 · Persona, soul, and skill templates shipped with the repo.
pythonclaw/templates
Connections 21
- 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.