NanoClaw Architecture and Runtime

1. The workspace shape

The README gives a remarkably clear architecture summary:

Area	Purpose
host process	routing, delivery, sweeps, session resolution
per-agent containers	run Claude or other provider-backed agent logic
SQLite session files	inbound and outbound message flow
channel adapters	connect to Telegram, Discord, Slack, and others
provider registry	configure Claude by default and other providers via skills

This is one of NanoClaw's biggest strengths: the architecture is explainable.

2. The runtime mental model

The upstream architecture sketch is:

1. a channel receives a message,
2. the host routes it to the right group and session,
3. the message lands in inbound.db,
4. the containerized runner processes it,
5. the result is written to outbound.db,
6. the host delivers it back through the channel adapter.

That is a strong design because it keeps responsibilities separated and avoids shared in-process agent state.

3. Why the two-database model matters

The README highlights that each session uses:

• one writer for inbound,
• one writer for outbound,
• no shared-memory IPC,
• and no fragile stdin piping.

That makes the runtime easier to reason about and more robust under background operation.

4. Skills over features

Another important architectural point is that channels and extra providers are meant to be skill-installed instead of permanently living in trunk.

That keeps forks lean and makes the project more composable.

5. What to read first in code

Start with:

1. the README architecture section,
2. src/index.ts,
3. router and delivery files,
4. container runner and provider surfaces,
5. groups/ and skill-installed modules.