Matters

Extend

One core. The rest plugs in.

The core knows mail, not servers or models. Everything outside it is an adapter you can replace or add.

How it is built

packages/core holds the domain and the use cases. It asks for what it needs through small interfaces, the ports. Each packages/adapter-* answers one of them. A check on every change stops the core from importing an adapter.

AdapterWhat it plugs in
adapter-imap adapter-smtpReading and sending mail
adapter-sqliteThe local database and search
adapter-claude-code adapter-codex adapter-ollamaWhere the agent runs
adapter-secretsPasswords, in the system keychain
adapter-mime adapter-composeParsing and writing messages
adapter-files adapter-filetextAttachments and the text inside them
adapter-autoconfigFinding a provider's servers

Add an agent runtime

A runtime is anything that takes instructions and text and gives back a value: a program on the computer, a local model, an API. This is the whole interface.

export interface AgentRuntimePort {
  readonly id: AgentRuntimeId;
  readonly name: string;

  /** What the runtime is on this machine. Sends no mail, spends nothing. */
  inspect(): Promise<AgentRuntimeInfo>;

  run(
    request: AgentRunRequest,
    options?: { readonly signal?: AbortSignal },
  ): Promise<AgentRunResult>;

  /** Optional: one turn that may call the tools Matters offers, and no others. */
  runWithTools?(request: AgentRunRequest, options: AgentToolRunOptions): Promise<AgentRunResult>;
}
  1. Make a package. Start from packages/adapter-ollama.
  2. Implement the port. Mail reaches a model as data, never as instructions. Keep it that way.
  3. Test it. packages/testkit has the fakes the other adapters use.
  4. Run the checks and open a pull request.
$ bun run typecheck
$ bun run test
$ bun run check:boundaries   # the core imports no adapter
$ bun run check:licenses

Wanted next

AdapterWhy
Browser sign-in (OAuth)Microsoft 365 and Outlook.com do not work without it.
Gmail API, JMAP, Microsoft GraphFaster sync than IMAP where a provider offers it.
API keysA runtime for any provider's API.
Linux and WindowsBuilds, a keychain for each, and people to test them.

Read more

The architecture, and every decision behind it, are in the repository. Matters is licensed under AGPL-3.0.