Architecture Overview

Wayland is one engine wrapped in two shells. Understanding the layers makes the rest of the docs click into place.

The engine loop

At the center is the agent loop: the engine sends your conversation to a model, streams the reply, and when the model asks to use a tool it runs that tool and feeds the result back. The loop repeats until the task is done or it hits a turn limit.

┌──────────────────────────────────────────────────────────────┐
│                     wayland-core (CLI / REPL)                  │
├──────────────────┬───────────────────────┬───────────────────┤
│  Config          │  Engine (agent loop)  │  Session Manager   │
│  (3-level merge) │  streaming + tools    │  save / resume     │
├──────────────────┼───────────────────────┼───────────────────┤
│  Providers       │  Tool Registry        │  Hook Executor     │
│  ├ Anthropic     │  ├ Built-in (8)       │  ├ pre_tool_use    │
│  ├ OpenAI        │  ├ MCP tools (N)      │  ├ post_tool_use   │
│  ├ Bedrock       │  └ Plan-mode tools    │  └ stop            │
│  └ Vertex AI     │                       │                    │
└──────────────────┴───────────────────────┴───────────────────┘

Providers and ProviderCompat

The provider layer speaks to each model API: Anthropic, OpenAI and its compatibles (DeepSeek, Ollama), Google Gemini, AWS Bedrock, and Google Vertex AI in the engine. A ProviderCompat layer handles each provider’s quirks through configuration rather than hardcoded branches, so adding or adjusting a provider is a config change, not a code change. The desktop catalog exposes 32 providers on top of these engine-native five.

The tool registry

Tools are how the agent acts on the world. The registry combines three sources:

Eight built-in tools: Read, Write, Edit, Bash, Grep, Glob, Delegate (sub-agents), and ToolSearch.
MCP tools: any number of tools provided by connected Model Context Protocol servers.
Plan-mode tools: a read-only subset used when the agent is designing a plan.

Concurrency-safe tools (Read, Grep, Glob) can run in parallel; tools that change state (Write, Edit, Bash) run one at a time. When tool names collide, MCP tools are auto-prefixed as mcp__{server}__{tool}.

MCP client

The engine is a full MCP client. It connects to servers over stdio, SSE, or streamable-http, performs the startup handshake, lists their tools, and registers them. Tools can be deferred so their schemas load only when needed, and a host driving the engine over the JSON stream can inject MCP servers at runtime.

Hooks

A hook executor fires on the tool lifecycle: pre_tool_use, post_tool_use, and stop. Hooks are how you wire in auto-format, lint, or audit steps that run automatically as the agent works.

Memory and sessions

The session manager saves conversations so you can resume them. Per-project memory indexes what happened across sessions so the agent can recall earlier decisions and context. In the desktop app this surfaces as the Memory page and the knowledge Wiki.

Keeping long sessions in budget

A compaction engine keeps token use under control with three tiers: microcompact, autocompact, and an emergency pass. Output compaction (off, safe, or full) and TOON encoding further trim cost, and Anthropic prompt caching reuses stable context for large savings on repeated runs.

How the desktop wraps it

The desktop app runs the engine as a backend and talks to it through the Agent Client Protocol (ACP). Around that engine, desktop processes host the things a GUI adds: channels, the team coordinator, the web server and WebUI for remote access, voice, and image generation. The result is that anything you set up in the engine behaves identically in the app, because it is the same engine.