Project Structure

The source tree is organized into three top-level directories (core/, services/, plugins/) plus entry-point modules at the root. Each layer has a specific role and a strict import policy that prevents unintended coupling.

File Tree

src/
├── core/
│   ├── behaviours/behaviours.gleam   — 13 DI behaviour records
│   ├── types/                        — session, message, client, response, hooks, tool_def, logging, guardrails
│   ├── config/                       — config.gleam (loader), helpers.gleam
│   ├── loop/                         — orchestrator, runner, context, compression, error, guardrails
│   ├── registry/                     — registry.gleam (pure dispatch), builder.gleam (wires tools)
│   ├── session/                      — session.gleam (state), handler.gleam (composition)
│   ├── tool/                         — tool.gleam (types), executor.gleam (validation + parallel exec)
│   ├── schedule.gleam                — shared cron schedule parser
│   └── service.gleam                 — Service shape definition
├── services/
│   ├── api/openai/completions.gleam
│   ├── storage/                      — db, db_behaviour, session_db, session_db_behaviour, memory_db, cron_db, schema, cfg
│   ├── admin/, context/, cron/, guardrails/, harness/, logger/, notifications/, persona/, pulse/, supervisor/, titler/, tokens/
├── plugins/
│   ├── types.gleam                   — Plugin, PluginType (Tool, Gateway, Hook, MemoryProvider)
│   ├── gateways/                     — types.gleam, supervisor.gleam, telegram/ (8 files), tui/README.md (planned)
│   ├── hooks/                        — types.gleam, context_compressor/, reflection/, tool_guardrails/
│   ├── memory/file_memory/
│   └── tools/                        — bash/, browser/, code/, cron/, memory/, session_search/, web/, gateways/telegram/
├── agent.gleam, agent_app.gleam, agent_admin.gleam, agent_supervisor.gleam

Layer Responsibilities

Core (src/core/)

The lightweight wireframe. Core defines all shared types, the 13 behaviour records (structural contracts for DI), the pure conversation loop that orchestrates API-tool rounds, the tool registry, session state, and configuration loading. Core does not perform I/O directly -- it delegates to services and plugins through behaviour records.

Import policy: Must NOT import from services/ or plugins/. There are exactly 6 exceptions to this rule, documented in Blessed Violators.

Services (src/services/)

Fixed branches that perform real work. Each service conforms to the Service shape defined in core/service.gleam. Services handle HTTP calls (LLM completions), SQLite persistence, shell execution, token estimation, and other concrete operations. They are built-in and not user-swappable.

Import policy: May import from core/, other services, and external libraries.

Plugins (src/plugins/)

Swappable, shape-conforming, user-extensible components. Each plugin conforms to the Plugin shape from plugins/types.gleam and declares a PluginType (Tool, Gateway, Hook, or MemoryProvider). Built-in and user-provided plugins follow the same shapes. Users can add custom plugins in ~/.agent/tools/, ~/.agent/hooks/, etc.

Import policy: May import from core/, services/ (via DI), other plugins, and external libraries.

Top-Level Entry Points

Module	Purpose
agent.gleam	CLI REPL entry point -- interactive chat in the terminal
agent_app.gleam	Daemon entry point -- starts the agent as a background service
agent_admin.gleam	Admin CLI -- connects to the running agent for inspection and control
agent_supervisor.gleam	Root OTP supervisor -- wires all behaviours, starts logger, gateway supervisor, and service supervisor

Next Steps

• Dependency Injection -- How behaviour records decouple layers
• Core Modules -- Detailed reference for each core module
• Services -- Reference for each service
• Plugins -- Plugin types, shapes, and how to write custom plugins