Skip to content

Concepts ​

The kernel and plugins ​

The app is a small kernel plus plugins. The kernel holds only what every feature needs:

  • Domain model: participants, rooms, messages and blocks.
  • Ports: the interfaces adapters implement, such as ConversationProvider for agents and RoomPersistence for storage.
  • Registry: where plugins register renderers, tabs, providers, surfaces and slot contributions.
  • Store: applies events from agents, streams text smoothly, and tracks delivery states, tasks, prompts and room status.
  • Shell: the window, made of named slots with fallbacks.
  • Design kit: shared building blocks so every plugin looks native.

Everything else is a plugin. The kernel even runs with zero plugins: it opens a window, shows every block as plain text and leaves every slot empty.

Built-ins are replaceable. Registering something with an existing ID overrides it; later registrations win.

Ports and adapters ​

The kernel never imports a protocol or an adapter. Agents, storage and wire protocols plug in through ports, and dependencies always point inward. That's what lets one app talk to agents from any provider.

Rooms and participants ​

A room is a conversation. Its participants can be you, your teammates and agents, each from a different provider. Agents are one kind of participant: nothing in the kernel requires an LLM.

An agent in your library has a name, a color, a provider, instructions and default permissions. Rooms started from an agent keep up with changes to it.

A room can hold several agents. Three rules say who answers: the agents you @mention; with no mention, the room's moderator; with no moderator, everyone. Agents know who else is in the room, can hand off work to each other and ask to be called back with the result, and may pass when they have nothing to add. A turn limit keeps a chain of agent turns from running on. Every agent sees the room the same way, whichever plugin it comes from. See Rooms with several agents.

Blocks ​

A message is a list of blocks. A block is a type, a JSON payload and optional fallback text. The kernel never switches over a fixed list of types: a registered renderer draws a block, and anything unknown shows its fallback text.

So new content is a new block type, not an app change. Plugins that cooperate agree on a type string and a payload, not on each other's code. Namespace your own types, like acme.diff.

Events ​

An agent talks to a room by streaming events: start a message, append text, add a block, end the message, report live status, update a task. The kernel applies them in order and coalesces text so long replies stay smooth. See the full list in Connect your first agent.

Prompts and permissions ​

An agent asks the user something with a prompt (ask in the SDK): an approval, a choice or a short typed answer. A room with an unanswered prompt shows as Needs You. When the user picks "Always allow", the room remembers a plain-language grant, and later matching requests are answered automatically. Users can see and revoke every grant.

Room status ​

Every room has a status: offline, needs you, stalled, working, failed or idle, in that order of precedence. A room is stalled when it's working but has been quiet for 20 seconds. The sidebar, the Needs You section and the Dock badge are all plugins that read it.

Surfaces ​

Some blocks are bigger than a message. A surface is an expanded view of a block, like a live terminal, a web page or a map, opened beside the chat or in its own window. The kernel owns the container; plugins own what's inside.

All your Agents, playing nicely in one Playground.