How warengonzaga/tinyclaw works
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: core Agent core · web Web app · queue Queue · cli CLI
Components 23
Apps
User-facing entry points and presentation surfaces.
Core packages
Reusable runtime and agent subsystems.
- Agent core · Central agent loop, message handling, database access, model defs, auth, and update checks.
packages/core - Queue · Serializes incoming work per session before it reaches the core loop.
packages/queue - Router · Classifies requests and chooses a provider or model tier based on complexity and installed plugins.
packages/router - Compactor · Compresses and tiers context through rule-based reduction, deduplication, and summarization.
packages/compactor - Memory · Adaptive memory with episodic storage and semantic lookup over persisted state.
packages/memory - Heartware · Loads identity metadata, templates, traits, and runtime guardrails around the agent persona.
packages/heartware - Shield · Parses and enforces SHIELD-style threat rules and safety constraints.
packages/shield - Sandbox · Worker-like isolated runtime for executing code safely.
packages/sandbox - Shell · Permission-gated shell execution boundary for controlled system commands.
packages/shell - Secrets · Encrypted secret handling and isolation for sensitive credentials.
packages/secrets - Delegation · Manages sub-agent lifecycle, orientation, templates, blackboard, and background coordination.
packages/delegation - Intercom · Lightweight pub/sub bus for inter-agent events with bounded history.
packages/intercom - Learning · Detects behavioral patterns so the agent can improve over time.
packages/learning - Nudge · Generates companion-style proactive behaviors and suggestions.
packages/nudge - Pulse · Triggers time-based actions and delayed agent activity.
packages/pulse - Config · Validated runtime configuration and tool settings management.
packages/config - Plugin loader · Discovers and loads provider and channel plugins.
packages/plugins
Plugins
Loaded channel and provider extensions.
- Discord plugin · Adapts Discord messaging into the core channel surface.
plugins/channel/plugin-channel-discord - Friends plugin · Web/channel plugin that provides a friend-facing chat surface and server.
plugins/channel/plugin-channel-friends - OpenAI plugin · Provider adapter for OpenAI-style model access.
plugins/provider/plugin-provider-openai
Connections 26
- 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.