Agent System

The kernel doesn't handle everything itself. It delegates to five specialized sub-agents, each with its own prompt, tools, and personality. The kernel selects which agent to spawn based on the user's request.

This architecture follows a broader shift toward agents that can work through complete tasks instead of only suggesting code. GitHub documents coding agents that research a repository, change code on a branch, and open a pull request for review (GitHub Docs). Claude Code likewise supports resumable sessions and explicit turn limits for unattended commands (Anthropic CLI reference). Matrix applies those patterns inside its own kernel and persistent workspace.

Core Agents

The five core agents are defined in packages/kernel/src/agents.ts and their prompts live in home/agents/custom/ as markdown files.

How Agent Selection Works

User message
  |
  +---> Kernel (main agent)
          |
          +---> Reads agent descriptions from AgentDefinition records
          +---> Selects the best agent based on request
          +---> Spawns sub-agent via Agent SDK Task tool
          +---> Sub-agent executes with its own tools and prompt
          +---> Result flows back to kernel -> user

The kernelOptions() function in packages/kernel/src/options.ts assembles the agent set by calling getCoreAgents() for built-in agents and loadCustomAgents() for user-defined agents from ~/agents/custom/.

AgentDefinition

Each agent is represented by an AgentDefinition object with:

• description -- used by the kernel to decide when to spawn this agent
• prompt -- the agent's system prompt (from the markdown file body)
• tools -- explicit allow-list of tools the agent can use
• disallowedTools -- tools to deny (alternative to tools)
• model -- which Claude model to use (defaults to Opus)
• maxTurns -- maximum conversation turns before stopping

Saved Bot conversations

In Chat, open a saved Bot from the Bot list to enter its dedicated conversation. Selecting a Bot mention opens that same conversation. The Bot's name, instructions, and model remain associated with it when you close, reopen, or reconnect.

For an older or custom Bot that has no dedicated conversation yet, the first open creates one. Later opens return to the same conversation and its history, even after renaming the Bot. Two Bots with the same name still have separate conversations. Existing ordinary Chats keep their messages and are not moved into the new Bot conversation. An archived or deleted dedicated conversation is not recreated automatically.

Opening an older Bot preserves its saved instructions, configuration, executor, and model. You do not need to recreate the Bot or manually update a database for each user. If its saved executor or model is unavailable, configure that dependency before sending a message; opening the Bot does not switch it to a different executor.

Create a Bot and choose its connection

In the Chat sidebar, click Agents to manage saved Bots in Your AI team. Click the + beside Agents to open New agent, where Start from scratch appears alongside the preset Bots. The New agent button in Your AI team opens the same chooser.

Choose Start from scratch to enter your own name and instructions, or select a preset to open its setup. Cancelling the scratch form returns to the chooser without creating a Bot. Search and category filters help you browse presets; Start from scratch remains available beside them.

In the creation form, choose the connection and model for the new Bot. With ChatGPT subscription, choose a supported GPT model from your connected account. Keep the connected device online while interactive Bots use that subscription.

Recipe setup also offers Automatic · managed by this computer. Automatic uses an eligible computer-configured connection. Choosing a subscription is explicit: select ChatGPT subscription and its model when you want that account to fund the Bot.

Use Refresh models if a newly connected account or recovered model is missing. Refresh updates the choices while keeping the name, instructions, recipe and selected connection in your draft. If the selected model or account becomes unavailable, reconnect or choose an available model before saving.

Creating or saving a Bot does not run it or grant access to connected apps. Open its dedicated conversation and send a request when you are ready. Existing saved custom Bots continue to use their saved executor and approval flow.

Bot features and access

Recipe Bots provide the features supported by their recipe, including structured tasks, integration permissions, and Bot memory. Older custom Bots keep the features and approval flow of their saved executor. Recipe-only controls remain unavailable for those older custom Bots.

Opening a Bot does not add integration permissions or grant Full access. When a saved executor requires Full access, confirm it for the request before sending. Existing conversations and permissions remain intact.

Large reviews in small batches

For a large review, ask the Bot to process a small batch, save compact recommendations, and report its progress before continuing. For example: "Review five messages at a time, save each result, and resume only messages without a saved result." A request to review all mail should include the intended folders and exclusions, and require complete pagination and message coverage before the final report claims completion.

On a runtime with bounded Bot inference, the Bot can shorten historical tool details in its working model context while retaining the saved conversation and checkpoint files. Small batches continue in the same Bot conversation. Save the information needed for later recommendations rather than relying on old raw tool responses staying in working context.

Keep the review basis explicit: a recommendation based on headers and snippets is different from a full-body review. Mark incomplete reads for follow-up and report partial progress after an interruption. A read-only recipe can propose actions, but cannot send, label, archive, or delete mail.

Custom Agents

Create your own agent by adding a markdown file to ~/matrixos/agents/custom/:

---
name: analyst
description: Analyzes data files and produces reports with visualizations
model: claude-sonnet-4-6
maxTurns: 10
---

You are a data analyst agent. When given data files, you:
1. Read and understand the data structure
2. Identify patterns and anomalies
3. Create visualizations as HTML files
4. Write a summary report

Always save outputs to ~/data/reports/.

Custom agents override core agents if they share the same name. The parseFrontmatter() function extracts YAML metadata and the prompt body.

SOUL Identity

The SOUL system defines your AI's personality. Three files in ~/matrixos/system/ shape every interaction:

These are loaded by buildSystemPrompt() in packages/kernel/src/prompt.ts and injected into the system prompt for every kernel invocation.

Skills System

Skills are directory-based Agent Skills in ~/.agents/skills/<name>/SKILL.md that extend what the kernel can do. They use a demand-loading pattern to keep the context window lean.

The open specification recommends keeping the main SKILL.md below 500 lines and loading supporting references only when needed. It describes three disclosure levels: compact metadata at startup, full instructions on activation, and supporting resources on demand (Agent Skills specification).

How Skills Work

1. TOC in prompt -- buildSkillsToc() generates a table of contents listing all skills. This is injected into the system prompt so the kernel knows what's available.
2. Trigger matching -- each skill has a description in its frontmatter that helps the model choose when to load it.
3. On-demand loading -- when a request matches, the kernel calls the load_skill IPC tool to fetch the full skill body into context.

Skill File Format

---
name: matrix-app-builder
description: Build Matrix OS apps as Vite React TypeScript projects with matrix.json manifests, Matrix theme integration, Postgres-backed app data, and production build verification.
version: 1.0.0
author: Matrix OS
license: MIT
---

Default to Vite, React 19, TypeScript, `runtime: "vite"`, and Matrix/Postgres bridge APIs.

Built-in Skills

Matrix OS ships a canonical coding pack under skills/matrix/: matrix-app-builder, matrix-design-system, matrix-integrations, matrix-dev-vps, and matrix-debug-app. Runtime startup syncs that pack into Matrix, Claude Code, Codex, and Hermes skill folders.

Onboarding

The onboarding system uses a persona engine with 7 roles (developer, student, creative, etc.) to customize the initial setup. The get_persona_suggestions and write_setup_plan IPC tools drive this process, provisioning skills and configuring the system based on the user's needs.