# warengonzaga/tinyclaw architecture

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

- Interactive diagram: https://gitdiagram.com/warengonzaga/tinyclaw
- Repository: https://github.com/warengonzaga/tinyclaw

## Overview

1. **Monorepo shape**
   - Tiny Claw is a Bun-based TypeScript monorepo split into a small set of reusable `packages/`, extension `plugins/`, and two user-facing apps under `src/` (`cli`, `web`, plus a `landing` site).
   - The architecture is intentionally “tiny core, plugin everything”: the core packages implement the agent brain and safety rails, while channels and external providers are loaded as plugins.

2. **Primary entry points**
   - `src/cli` is the operational entry point for setup, start, config, backup, purge, seed, and web bootstrap commands.
   - `src/web` is the local interactive UI and server layer, built with Svelte/Vite, that presents the conversational experience and event streaming.
   - `src/landing` is a separate marketing/intro site and is architecturally isolated from the agent runtime.

3. **Main runtime flow**
   - Incoming user messages enter through a channel surface: CLI, web UI, or a channel plugin such as Discord/Friends.
   - Requests are serialized per session by the queue layer, then passed into the core loop where context is assembled, memory is consulted, routing is decided, tools may be invoked, and a provider is selected for LLM calls.
   - Responses and lifecycle events are then streamed back to the originating channel/UI.

4. **Core agent brain**
   - `packages/core` is the central orchestration layer: it contains the agent loop, database access, message types, model definitions, owner auth, LLM integration, and update checks.
   - This package is the narrow hub that other subsystems connect through, rather than a large monolithic service.

5. **Context management and model cost control**
   - `packages/compactor` implements the 4-layer context compaction pipeline: rule-based pre-compression, deduplication, summarization, and tiered outputs.
   - `packages/router` classifies queries across multiple dimensions and selects a provider/model tier based on complexity and what plugins are installed.
   - Together these two layers control prompt size and LLM spend before the request reaches the provider.

6. **Memory and learning**
   - `packages/memory` provides adaptive persistence, including episodic memory and SQLite FTS-style retrieval for semantic lookup.
   - `packages/learning` detects behavioral patterns so the agent can improve over time instead of treating all conversations as flat history.
   - `packages/nudge` adds proactive “companion” behavior, while `packages/pulse` is the scheduler for time-based actions.

7. **Personality and identity**
   - `packages/heartware` is the personality engine: it loads and manages SOUL/identity-style metadata, templates, and traits that define the agent’s character.
   - It also includes rate limiting, audit, backup, sandboxing hooks, and error handling around that personality layer, making identity part of the runtime rather than just a prompt string.

8. **Safety and execution boundaries**
   - `packages/shield` enforces SHIELD.md-style threat rules with parsing, matching, and engine enforcement.
   - `packages/sandbox` and `packages/shell` are separate execution boundaries: the sandbox runs code in a worker-like environment, while shell execution is permission-gated and controlled.
   - `packages/secrets` isolates encrypted secret handling, and `packages/heartware`/`packages/core` add backup and audit support around sensitive operations.

9. **Delegation and coordination**
   - `packages/delegation` is the sub-agent orchestration system: it manages lifecycle, runner behavior, orientation, templates, timeout estimation, a blackboard, and background coordination.
   - `packages/intercom` provides a lightweight pub/sub bus for inter-agent events with bounded history and wildcard-style subscription behavior.
   - This makes delegation an internal collaboration subsystem, not just another tool call.

10. **Plugin boundary**
   - `packages/plugins` is the discovery/loading layer, while concrete plugins live under `plugins/`.
   - Channel plugins adapt external messaging platforms into the core, and provider plugins adapt model vendors into the routing/provisioning system.
   - The current tree shows a Discord channel plugin, a Friends web/channel plugin, and an OpenAI provider plugin; the README also indicates a built-in Ollama Cloud path in core.

11. **Persistence and configuration**
   - `packages/config` manages validated runtime configuration and tool settings, which is important because the project emphasizes self-configuration over hand-written config files.
   - `packages/core`, `packages/memory`, `packages/delegation`, and `packages/secrets` imply SQLite-backed persistence as a shared storage boundary for agent state, memory, and credentials.

12. **UI/runtime presentation**
   - `src/web` is not just static UI; it includes server-side code, a security DB, and hatching/preview components, suggesting a locally hosted interactive experience with real-time events.
   - `src/cli` also owns the operational UI for terminal-driven setup and lifecycle control, so the product has both interactive and headless entry points.

13. **Support tooling and delivery**
   - The repo uses Bun, Biome, package-level tests, and GitHub Actions for CI/release/container/landing workflows.
   - That tooling reinforces the repo’s boundaries: packages are tested in isolation, while apps are built and deployed separately.

Main entry points: [`packages/core`](https://github.com/warengonzaga/tinyclaw/tree/main/packages/core) (Agent core), [`src/web`](https://github.com/warengonzaga/tinyclaw/tree/main/src/web) (Web app), [`packages/queue`](https://github.com/warengonzaga/tinyclaw/tree/main/packages/queue) (Queue), [`src/cli`](https://github.com/warengonzaga/tinyclaw/tree/main/src/cli) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_apps["Apps"]
  node_cli["CLI<br/>entrypoint"]
  node_web["Web app<br/>ui/server"]
  node_landing["Landing<br/>marketing site"]
end

subgraph group_core["Core packages"]
  node_core["Agent core<br/>orchestrator"]
  node_queue["Queue"]
  node_router["Router"]
  node_compactor["Compactor<br/>context pipeline"]
  node_memory[("Memory<br/>persistence/retrieval")]
  node_heartware["Heartware<br/>personality engine"]
  node_shield{{"Shield<br/>policy engine"}}
  node_sandbox["Sandbox<br/>execution boundary"]
  node_shell["Shell<br/>command runner"]
  node_secrets[("Secrets<br/>credential store")]
  node_delegation["Delegation<br/>sub-agent system"]
  node_intercom(("Intercom<br/>event bus"))
  node_learning["Learning<br/>pattern detector"]
  node_nudge(("Nudge<br/>proactive companion"))
  node_pulse(("Pulse<br/>scheduler"))
  node_config["Config<br/>settings manager"]
  node_pluginspkg["Plugin loader<br/>discovery layer"]
end

subgraph group_plugins["Plugins"]
  node_discord["Discord plugin<br/>channel plugin"]
  node_friends["Friends plugin<br/>channel plugin"]
  node_openai["OpenAI plugin<br/>provider plugin"]
end

node_cli -->|"reads setup"| node_config
node_cli -->|"starts runtime"| node_core
node_cli -->|"boots web"| node_web
node_web -->|"submits messages"| node_queue
node_discord -->|"ingests chat"| node_queue
node_friends -->|"ingests chat"| node_queue
node_queue -->|"dispatches"| node_core
node_core -->|"builds context"| node_compactor
node_core -->|"retrieves memory"| node_memory
node_core -->|"routes request"| node_router
node_router -->|"resolves plugins"| node_pluginspkg
node_pluginspkg -->|"loads provider"| node_openai
node_core -->|"applies persona"| node_heartware
node_core -->|"checks policy"| node_shield
node_core -->|"isolates code"| node_sandbox
node_core -->|"runs commands"| node_shell
node_core -->|"uses credentials"| node_secrets
node_core -->|"spawns agents"| node_delegation
node_delegation -->|"publishes events"| node_intercom
node_core -->|"tracks patterns"| node_learning
node_core -->|"proposes actions"| node_nudge
node_core -->|"schedules tasks"| node_pulse
node_core -->|"reads runtime settings"| node_config
node_core -->|"loads extensions"| node_pluginspkg
node_web -->|"streams events"| node_core
node_landing -.->|"separate site"| node_web

click node_cli "https://github.com/warengonzaga/tinyclaw/tree/main/src/cli"
click node_web "https://github.com/warengonzaga/tinyclaw/tree/main/src/web"
click node_landing "https://github.com/warengonzaga/tinyclaw/tree/main/src/landing"
click node_core "https://github.com/warengonzaga/tinyclaw/tree/main/packages/core"
click node_queue "https://github.com/warengonzaga/tinyclaw/tree/main/packages/queue"
click node_router "https://github.com/warengonzaga/tinyclaw/tree/main/packages/router"
click node_compactor "https://github.com/warengonzaga/tinyclaw/tree/main/packages/compactor"
click node_memory "https://github.com/warengonzaga/tinyclaw/tree/main/packages/memory"
click node_heartware "https://github.com/warengonzaga/tinyclaw/tree/main/packages/heartware"
click node_shield "https://github.com/warengonzaga/tinyclaw/tree/main/packages/shield"
click node_sandbox "https://github.com/warengonzaga/tinyclaw/tree/main/packages/sandbox"
click node_shell "https://github.com/warengonzaga/tinyclaw/tree/main/packages/shell"
click node_secrets "https://github.com/warengonzaga/tinyclaw/tree/main/packages/secrets"
click node_delegation "https://github.com/warengonzaga/tinyclaw/tree/main/packages/delegation"
click node_intercom "https://github.com/warengonzaga/tinyclaw/tree/main/packages/intercom"
click node_learning "https://github.com/warengonzaga/tinyclaw/tree/main/packages/learning"
click node_nudge "https://github.com/warengonzaga/tinyclaw/tree/main/packages/nudge"
click node_pulse "https://github.com/warengonzaga/tinyclaw/tree/main/packages/pulse"
click node_config "https://github.com/warengonzaga/tinyclaw/tree/main/packages/config"
click node_pluginspkg "https://github.com/warengonzaga/tinyclaw/tree/main/packages/plugins"
click node_discord "https://github.com/warengonzaga/tinyclaw/tree/main/plugins/channel/plugin-channel-discord"
click node_friends "https://github.com/warengonzaga/tinyclaw/tree/main/plugins/channel/plugin-channel-friends"
click node_openai "https://github.com/warengonzaga/tinyclaw/tree/main/plugins/provider/plugin-provider-openai"

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_web,node_landing toneBlue
class node_core,node_queue,node_router,node_compactor,node_memory,node_heartware,node_shield,node_sandbox,node_shell,node_secrets,node_delegation,node_intercom,node_learning,node_nudge,node_pulse,node_config,node_pluginspkg toneAmber
class node_discord,node_friends,node_openai toneMint
```

## Components

### Apps

User-facing entry points and presentation surfaces.

- [CLI](https://github.com/warengonzaga/tinyclaw/tree/main/src/cli): entrypoint · Operational terminal entry point for setup, lifecycle, and maintenance commands. · `src/cli`
- [Web app](https://github.com/warengonzaga/tinyclaw/tree/main/src/web): ui/server · Local interactive Svelte/Vite UI and server for conversational sessions and streaming events. · `src/web`
- [Landing](https://github.com/warengonzaga/tinyclaw/tree/main/src/landing): marketing site · Separate public intro site, isolated from the agent runtime. · `src/landing`

### Core packages

Reusable runtime and agent subsystems.

- [Agent core](https://github.com/warengonzaga/tinyclaw/tree/main/packages/core): orchestrator · Central agent loop, message handling, database access, model defs, auth, and update checks. · `packages/core`
- [Queue](https://github.com/warengonzaga/tinyclaw/tree/main/packages/queue): session queue · Serializes incoming work per session before it reaches the core loop. · `packages/queue`
- [Router](https://github.com/warengonzaga/tinyclaw/tree/main/packages/router): model router · Classifies requests and chooses a provider or model tier based on complexity and installed plugins. · `packages/router`
- [Compactor](https://github.com/warengonzaga/tinyclaw/tree/main/packages/compactor): context pipeline · Compresses and tiers context through rule-based reduction, deduplication, and summarization. · `packages/compactor`
- [Memory](https://github.com/warengonzaga/tinyclaw/tree/main/packages/memory): persistence/retrieval · Adaptive memory with episodic storage and semantic lookup over persisted state. · `packages/memory`
- [Heartware](https://github.com/warengonzaga/tinyclaw/tree/main/packages/heartware): personality engine · Loads identity metadata, templates, traits, and runtime guardrails around the agent persona. · `packages/heartware`
- [Shield](https://github.com/warengonzaga/tinyclaw/tree/main/packages/shield): policy engine · Parses and enforces SHIELD-style threat rules and safety constraints. · `packages/shield`
- [Sandbox](https://github.com/warengonzaga/tinyclaw/tree/main/packages/sandbox): execution boundary · Worker-like isolated runtime for executing code safely. · `packages/sandbox`
- [Shell](https://github.com/warengonzaga/tinyclaw/tree/main/packages/shell): command runner · Permission-gated shell execution boundary for controlled system commands. · `packages/shell`
- [Secrets](https://github.com/warengonzaga/tinyclaw/tree/main/packages/secrets): credential store · Encrypted secret handling and isolation for sensitive credentials. · `packages/secrets`
- [Delegation](https://github.com/warengonzaga/tinyclaw/tree/main/packages/delegation): sub-agent system · Manages sub-agent lifecycle, orientation, templates, blackboard, and background coordination. · `packages/delegation`
- [Intercom](https://github.com/warengonzaga/tinyclaw/tree/main/packages/intercom): event bus · Lightweight pub/sub bus for inter-agent events with bounded history. · `packages/intercom`
- [Learning](https://github.com/warengonzaga/tinyclaw/tree/main/packages/learning): pattern detector · Detects behavioral patterns so the agent can improve over time. · `packages/learning`
- [Nudge](https://github.com/warengonzaga/tinyclaw/tree/main/packages/nudge): proactive companion · Generates companion-style proactive behaviors and suggestions. · `packages/nudge`
- [Pulse](https://github.com/warengonzaga/tinyclaw/tree/main/packages/pulse): scheduler · Triggers time-based actions and delayed agent activity. · `packages/pulse`
- [Config](https://github.com/warengonzaga/tinyclaw/tree/main/packages/config): settings manager · Validated runtime configuration and tool settings management. · `packages/config`
- [Plugin loader](https://github.com/warengonzaga/tinyclaw/tree/main/packages/plugins): discovery layer · Discovers and loads provider and channel plugins. · `packages/plugins`

### Plugins

Loaded channel and provider extensions.

- [Discord plugin](https://github.com/warengonzaga/tinyclaw/tree/main/plugins/channel/plugin-channel-discord): channel plugin · Adapts Discord messaging into the core channel surface. · `plugins/channel/plugin-channel-discord`
- [Friends plugin](https://github.com/warengonzaga/tinyclaw/tree/main/plugins/channel/plugin-channel-friends): channel plugin · Web/channel plugin that provides a friend-facing chat surface and server. · `plugins/channel/plugin-channel-friends`
- [OpenAI plugin](https://github.com/warengonzaga/tinyclaw/tree/main/plugins/provider/plugin-provider-openai): provider plugin · Provider adapter for OpenAI-style model access. · `plugins/provider/plugin-provider-openai`

## Connections

- CLI → Config: reads setup · CLI commands load and manage validated configuration.
- CLI → Agent core: starts runtime · Bootstraps the agent process and operational commands.
- CLI → Web app: boots web · CLI can start or prepare the local web experience.
- Web app → Queue: submits messages · Interactive sessions enter the serialized request queue.
- Discord plugin → Queue: ingests chat · Channel plugin forwards inbound messages into the session queue.
- Friends plugin → Queue: ingests chat · Friends surface forwards inbound messages into the queue.
- Queue → Agent core: dispatches · Queued session work is handed to the core loop.
- Agent core → Compactor: builds context · Core prepares compacted prompt context before model calls.
- Agent core → Memory: retrieves memory · Core consults persistent memory during response assembly.
- Agent core → Router: routes request · Core delegates model/provider selection to the router.
- Router → Plugin loader: resolves plugins · Routing decisions depend on available provider plugins.
- Plugin loader → OpenAI plugin: loads provider · Plugin loader discovers provider implementations.
- Agent core → Heartware: applies persona · Core incorporates identity, traits, and persona templates.
- Agent core → Shield: checks policy · Safety rules gate sensitive or risky actions.
- Agent core → Sandbox: isolates code · Code execution is offloaded into the sandbox boundary.
- Agent core → Shell: runs commands · Shell execution is permission-controlled and mediated.
- Agent core → Secrets: uses credentials · Sensitive credentials are read through the secrets store.
- Agent core → Delegation: spawns agents · Sub-agent orchestration is handled by the delegation subsystem.
- Delegation → Intercom: publishes events · Delegated agents coordinate via the inter-agent bus.
- Agent core → Learning: tracks patterns · Observed behavior feeds learning and adaptation.
- Agent core → Nudge: proposes actions · Proactive companion behavior emerges from nudging.
- Agent core → Pulse: schedules tasks · Time-based actions are managed by the scheduler.
- Agent core → Config: reads runtime settings · Core and subsystems share validated configuration.
- Agent core → Plugin loader: loads extensions · Core relies on the plugin boundary for channels and providers.
- Web app → Agent core: streams events · The web UI consumes lifecycle and conversational events from core.
- Landing → Web app: separate site · Landing is architecturally isolated from the runtime UI.