Architecture

RantAIClaw is trait-driven and factory-registered. Every major extension point — providers, channels, tools, memory backends, observers, runtime adapters, peripherals — is defined as a Rust trait, with concrete implementations registering themselves via factory modules. To add a capability, you implement a trait and register it; you almost never modify orchestration code.

Around that core sit two organizing layers worth knowing about up front:

• The profile system — everything about a running agent (config, memory, persona, skills, secrets, audit) lives under ~/.rantaiclaw/profiles/<active>/. See Profiles.
• The subsystem map — 30+ Rust modules under src/, each with a single responsibility. The map below summarizes the ones you’ll touch most often.

The seven extension traits

Top-level subsystem map

The actual src/ tree is broader than the seven traits would suggest. The full top-level subsystems:

This is what makes rantaiclaw a single binary that can do a lot — the responsibilities are partitioned narrowly, so each subsystem stays small and auditable.

Boundary contract

These rules keep the architecture stable as the codebase grows:

• Concrete integrations depend on traits and config, never on each other. Provider code does not import channel internals. Tool code does not mutate gateway policy directly.
• Each subsystem owns a single concern. Orchestration in agent/. Transport in channels/. Model I/O in providers/. Policy in security/. Execution in tools/.
• New shared abstractions wait for the rule of three. Duplicate small logic locally rather than create premature abstractions.
• Config keys are public contract. Adding, renaming, or removing a config key requires documented compatibility impact and a migration path.

Blast radius — risk tiers

Validation depth scales with tier:

When in doubt, classify higher.

The daemon’s role

rantaiclaw daemon is the production deployment shape. It boots:

• the gateway HTTP server
• each enabled channel’s listen task
• the heartbeat / scheduler / cron loops

Each of these runs in its own tokio task, supervised with exponential-backoff restart on crash (src/daemon/mod.rs). A misbehaving channel doesn’t take down the gateway and vice versa.

Why size and determinism matter

Two design constraints visible everywhere in the codebase:

1. Binary size is a product goal. The release profile uses opt-level = "z", lto = "fat", codegen-units = 1, strip = true, panic = "abort". Convenience dependencies are scrutinized.
2. Determinism is a CI goal. Tests avoid flaky timing or network dependence. Local validation maps exactly to CI expectations.

Breaking either requires explicit justification.

Where to read next

• Profiles — the per-profile workspace under ~/.rantaiclaw/profiles/<name>/
• Agent Loop — what happens between message arriving and reply going out
• Autonomy Levels — the 3-level runtime enum and L1–L4 preset bundles
• Channels & Providers — the two largest extension surfaces
• Tools & Skills — how the agent acts on the world
• Security Model — the deny-by-default boundaries