# netclaw-dev/netclaw architecture

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

- Interactive diagram: https://gitdiagram.com/netclaw-dev/netclaw
- Repository: https://github.com/netclaw-dev/netclaw

## Overview

Netclaw is a self-hosted autonomous operations agent: users connect through the CLI or a chat channel, the daemon hosts sessions, invokes tools and persists state, then returns results through the initiating interface. The graph preserves the documented provider, memory, scheduling, background-job, and skill-feed capabilities as distinct branches. Several links are dashed because the relevant implementation was not sampled; paths identify existing source files or directories, not inferred filenames.

Main entry points: [`src/Netclaw.Daemon`](https://github.com/netclaw-dev/netclaw/tree/dev/src/Netclaw.Daemon) (Daemon), [`src/Netclaw.Actors/Sessions/SessionProtocol.cs`](https://github.com/netclaw-dev/netclaw/blob/dev/src/Netclaw.Actors/Sessions/SessionProtocol.cs) (Session Protocol), [`src/Netclaw.Channels`](https://github.com/netclaw-dev/netclaw/tree/dev/src/Netclaw.Channels) (Chat Channels), [`src/Netclaw.Cli/Program.cs`](https://github.com/netclaw-dev/netclaw/blob/dev/src/Netclaw.Cli/Program.cs) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Interfaces"]
  node_cli["CLI<br/>[Program.cs]"]
  node_daemon["Daemon<br/>[Netclaw.Daemon]"]
  node_chat_channels["Chat Channels<br/>[Netclaw.Channels]"]
  node_channel_pipeline["Channel Pipeline<br/>[ChannelPipeline.cs]"]
end

subgraph group_session["Agent Sessions"]
  node_session_protocol["Session Protocol<br/>[SessionProtocol.cs]"]
  node_turn_context["Turn Context<br/>[TurnContext.cs]"]
  node_tool_pipeline["Tool Execution"]
  node_compaction["Session Compaction"]
  node_recall["Memory Recall"]
end

subgraph group_capabilities["Agent Capabilities"]
  node_background_jobs["Background Jobs<br/>[Jobs]"]
  node_reminders["Reminders<br/>[Reminders]"]
  node_memory["Memory Curation"]
  node_embedding_warmup["Embedding Warmup"]
  node_skill_feeds["Skill Feeds"]
end

subgraph group_state["Configuration and State"]
  node_config["Configuration<br/>[NetclawPaths.cs]"]
  node_session_storage[("Session Storage")]
  node_storage_paths["Storage Layout"]
  node_oauth_storage[("OAuth Token State")]
end

subgraph group_integrations["External Integrations"]
  node_providers["LLM Providers"]
  node_llm_service["LLM Service"]
  node_chat_platforms["Chat Platforms"]
end

node_operator(("Operator"))

node_operator -->|"runs commands"| node_cli
node_cli -->|"connects locally"| node_daemon
node_daemon -->|"hosts sessions"| node_session_protocol
node_chat_platforms -.->|"sends messages"| node_chat_channels
node_chat_channels -.->|"routes input"| node_channel_pipeline
node_channel_pipeline -.->|"dispatches turns"| node_session_protocol
node_session_protocol -.->|"carries context"| node_turn_context
node_session_protocol -.->|"runs tools"| node_tool_pipeline
node_session_protocol -.->|"compacts history"| node_compaction
node_session_protocol -.->|"recalls memories"| node_recall
node_daemon -.->|"configures providers"| node_providers
node_providers -.->|"sends requests"| node_llm_service
node_tool_pipeline -.->|"dispatches jobs"| node_background_jobs
node_daemon -.->|"runs schedules"| node_reminders
node_recall -.->|"searches memories"| node_memory
node_embedding_warmup -.->|"repairs embeddings"| node_memory
node_daemon -.->|"manages feeds"| node_skill_feeds
node_daemon -->|"persists sessions"| node_session_storage
node_session_storage -->|"creates layouts"| node_storage_paths
node_daemon -->|"reads settings"| node_config
node_config -.->|"stores token state"| node_oauth_storage
node_chat_channels -.->|"sends responses"| node_chat_platforms

click node_cli "https://github.com/netclaw-dev/netclaw/blob/dev/src/Netclaw.Cli/Program.cs"
click node_daemon "https://github.com/netclaw-dev/netclaw/tree/dev/src/Netclaw.Daemon"
click node_chat_channels "https://github.com/netclaw-dev/netclaw/tree/dev/src/Netclaw.Channels"
click node_channel_pipeline "https://github.com/netclaw-dev/netclaw/blob/dev/src/Netclaw.Actors/Channels/ChannelPipeline.cs"
click node_session_protocol "https://github.com/netclaw-dev/netclaw/blob/dev/src/Netclaw.Actors/Sessions/SessionProtocol.cs"
click node_turn_context "https://github.com/netclaw-dev/netclaw/blob/dev/src/Netclaw.Actors/Channels/TurnContext.cs"
click node_tool_pipeline "https://github.com/netclaw-dev/netclaw/blob/dev/src/Netclaw.Actors/Sessions/Pipelines/SessionToolExecutionPipeline.cs"
click node_compaction "https://github.com/netclaw-dev/netclaw/blob/dev/src/Netclaw.Actors/Sessions/Pipelines/SessionCompactionPipeline.cs"
click node_recall "https://github.com/netclaw-dev/netclaw/blob/dev/src/Netclaw.Actors/Sessions/Pipelines/SessionRecallManager.cs"
click node_providers "https://github.com/netclaw-dev/netclaw/blob/dev/src/Netclaw.Providers/LlmProviderServiceExtensions.cs"
click node_background_jobs "https://github.com/netclaw-dev/netclaw/tree/dev/src/Netclaw.Actors/Jobs"
click node_reminders "https://github.com/netclaw-dev/netclaw/tree/dev/src/Netclaw.Actors/Reminders"
click node_memory "https://github.com/netclaw-dev/netclaw/blob/dev/src/Netclaw.Actors/Memory/MemoryCurationPipeline.cs"
click node_embedding_warmup "https://github.com/netclaw-dev/netclaw/blob/dev/src/Netclaw.Daemon/Services/EmbeddingWarmupHostedService.cs"
click node_skill_feeds "https://github.com/netclaw-dev/netclaw/tree/dev/feeds"
click node_config "https://github.com/netclaw-dev/netclaw/blob/dev/src/Netclaw.Configuration/NetclawPaths.cs"
click node_session_storage "https://github.com/netclaw-dev/netclaw/blob/dev/src/Netclaw.Daemon/Gateway/SqliteSessionStorageResolver.cs"
click node_storage_paths "https://github.com/netclaw-dev/netclaw/blob/dev/src/Netclaw.Tools.Abstractions/SessionStoragePaths.cs"
click node_oauth_storage "https://github.com/netclaw-dev/netclaw/blob/dev/src/Netclaw.Configuration/OAuthTokenExpiryStorage.cs"

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_daemon,node_chat_channels,node_channel_pipeline toneBlue
class node_session_protocol,node_turn_context,node_tool_pipeline,node_compaction,node_recall toneAmber
class node_background_jobs,node_reminders,node_memory,node_embedding_warmup,node_skill_feeds toneMint
class node_config,node_session_storage,node_storage_paths,node_oauth_storage toneRose
class node_providers,node_llm_service,node_chat_platforms,node_operator toneIndigo
```

## Components

### User Interfaces

- [CLI](https://github.com/netclaw-dev/netclaw/blob/dev/src/Netclaw.Cli/Program.cs): `src/Netclaw.Cli/Program.cs`
- [Daemon](https://github.com/netclaw-dev/netclaw/tree/dev/src/Netclaw.Daemon): `src/Netclaw.Daemon`
- [Chat Channels](https://github.com/netclaw-dev/netclaw/tree/dev/src/Netclaw.Channels): `src/Netclaw.Channels`
- [Channel Pipeline](https://github.com/netclaw-dev/netclaw/blob/dev/src/Netclaw.Actors/Channels/ChannelPipeline.cs): `src/Netclaw.Actors/Channels/ChannelPipeline.cs`

### Agent Sessions

- [Session Protocol](https://github.com/netclaw-dev/netclaw/blob/dev/src/Netclaw.Actors/Sessions/SessionProtocol.cs): `src/Netclaw.Actors/Sessions/SessionProtocol.cs`
- [Turn Context](https://github.com/netclaw-dev/netclaw/blob/dev/src/Netclaw.Actors/Channels/TurnContext.cs): `src/Netclaw.Actors/Channels/TurnContext.cs`
- [Tool Execution](https://github.com/netclaw-dev/netclaw/blob/dev/src/Netclaw.Actors/Sessions/Pipelines/SessionToolExecutionPipeline.cs): `src/Netclaw.Actors/Sessions/Pipelines/SessionToolExecutionPipeline.cs`
- [Session Compaction](https://github.com/netclaw-dev/netclaw/blob/dev/src/Netclaw.Actors/Sessions/Pipelines/SessionCompactionPipeline.cs): `src/Netclaw.Actors/Sessions/Pipelines/SessionCompactionPipeline.cs`
- [Memory Recall](https://github.com/netclaw-dev/netclaw/blob/dev/src/Netclaw.Actors/Sessions/Pipelines/SessionRecallManager.cs): `src/Netclaw.Actors/Sessions/Pipelines/SessionRecallManager.cs`

### Agent Capabilities

- [Background Jobs](https://github.com/netclaw-dev/netclaw/tree/dev/src/Netclaw.Actors/Jobs): `src/Netclaw.Actors/Jobs`
- [Reminders](https://github.com/netclaw-dev/netclaw/tree/dev/src/Netclaw.Actors/Reminders): `src/Netclaw.Actors/Reminders`
- [Memory Curation](https://github.com/netclaw-dev/netclaw/blob/dev/src/Netclaw.Actors/Memory/MemoryCurationPipeline.cs): `src/Netclaw.Actors/Memory/MemoryCurationPipeline.cs`
- [Embedding Warmup](https://github.com/netclaw-dev/netclaw/blob/dev/src/Netclaw.Daemon/Services/EmbeddingWarmupHostedService.cs): `src/Netclaw.Daemon/Services/EmbeddingWarmupHostedService.cs`
- [Skill Feeds](https://github.com/netclaw-dev/netclaw/tree/dev/feeds): `feeds`

### Configuration and State

- [Configuration](https://github.com/netclaw-dev/netclaw/blob/dev/src/Netclaw.Configuration/NetclawPaths.cs): `src/Netclaw.Configuration/NetclawPaths.cs`
- [Session Storage](https://github.com/netclaw-dev/netclaw/blob/dev/src/Netclaw.Daemon/Gateway/SqliteSessionStorageResolver.cs): `src/Netclaw.Daemon/Gateway/SqliteSessionStorageResolver.cs`
- [Storage Layout](https://github.com/netclaw-dev/netclaw/blob/dev/src/Netclaw.Tools.Abstractions/SessionStoragePaths.cs): `src/Netclaw.Tools.Abstractions/SessionStoragePaths.cs`
- [OAuth Token State](https://github.com/netclaw-dev/netclaw/blob/dev/src/Netclaw.Configuration/OAuthTokenExpiryStorage.cs): `src/Netclaw.Configuration/OAuthTokenExpiryStorage.cs`

### External Integrations

- [LLM Providers](https://github.com/netclaw-dev/netclaw/blob/dev/src/Netclaw.Providers/LlmProviderServiceExtensions.cs): `src/Netclaw.Providers/LlmProviderServiceExtensions.cs`
- **LLM Service**
- **Chat Platforms**

### Other components

- **Operator**

## Connections

- Operator → CLI: runs commands (evidence: `README.md`)
- CLI → Daemon: connects locally (evidence: `README.md`)
- Daemon → Session Protocol: hosts sessions (evidence: `README.md`)
- Chat Platforms → Chat Channels: sends messages
- Chat Channels → Channel Pipeline: routes input
- Channel Pipeline → Session Protocol: dispatches turns
- Session Protocol → Turn Context: carries context (evidence: `src/Netclaw.Actors/Channels/TurnContext.cs`)
- Session Protocol → Tool Execution: runs tools (evidence: `src/Netclaw.Actors/Sessions/Pipelines/SessionToolExecutionPipeline.cs`)
- Session Protocol → Session Compaction: compacts history
- Session Protocol → Memory Recall: recalls memories
- Daemon → LLM Providers: configures providers
- LLM Providers → LLM Service: sends requests
- Tool Execution → Background Jobs: dispatches jobs (evidence: `src/Netclaw.Actors/Sessions/Pipelines/SessionToolExecutionPipeline.cs`)
- Daemon → Reminders: runs schedules
- Memory Recall → Memory Curation: searches memories
- Embedding Warmup → Memory Curation: repairs embeddings
- Daemon → Skill Feeds: manages feeds
- Daemon → Session Storage: persists sessions (evidence: `README.md`)
- Session Storage → Storage Layout: creates layouts (evidence: `src/Netclaw.Daemon/Gateway/SqliteSessionStorageResolver.cs`)
- Daemon → Configuration: reads settings (evidence: `README.md`)
- Configuration → OAuth Token State: stores token state (evidence: `src/Netclaw.Configuration/OAuthTokenExpiryStorage.cs`)
- Chat Channels → Chat Platforms: sends responses
