Architecture

The Architecture section covers the internal design of the agent: how the codebase is organized, how modules connect, and how a message flows through the system from arrival to response.

The codebase follows a three-layer architecture with strict dependency direction:

Layer	Role	Extensible?
Core	Wireframe -- types, behaviours, pure loop orchestrator, config loader	No
Services	Fixed branches that do real work (HTTP, SQLite, shell)	No (built-in)
Plugins	Swappable, shape-conforming components	Yes (built-in + ~/.agent/)

Core modules must not import from services or plugins -- this keeps the wireframe decoupled from concrete implementations. Services and plugins wire into core via behaviour records (records of function fields that act as structural contracts), a form of dependency injection that works in Gleam without traits or protocols.

Start here

If you're new to the codebase, begin with Project Structure to see how the files are organized, then follow Request Flow to trace a conversation turn end-to-end.

In this section

• Project Structure -- File tree, layer responsibilities, import policies, top-level entry points
• Dependency Injection -- How behaviour records wire services and plugins into core without coupling
• Blessed Violators -- The 6 core modules that are allowed to import from services/ and plugins/, and why
• OTP Supervision -- The supervisor tree that manages service and gateway lifecycles
• Request Flow -- End-to-end walkthrough of a conversation turn with Mermaid diagram
• Core Modules -- Detailed reference for the core layer
• Services -- Detailed reference for each built-in service
• Plugins -- Plugin types, shapes, and how to write custom plugins