Coding Agents

Matrix OS runs coding agents on your Matrix computer, not on your laptop. The agent gets the same shell, files, repository, dev server, and Matrix skills that you see in the web shell — and it keeps running after you close your browser.

Supported agents

Four coding agents are supported:

Claude Code

Anthropic's coding agent. Launched with the claude command. Matrix skills are synced into Claude's skill discovery path.

Codex

OpenAI's CLI coding agent. Launched with the codex command.

OpenCode

Open-source coding agent. Launched with the opencode command.

Pi

Earendil's Pi coding agent. Launched with the pi command.

Hermes is separate

Hermes is the always-on Matrix chat agent, not a coding agent you install from the Terminal menu. See Hermes for details.

Installing an agent

The Terminal + menu shows all four agents and whether each one is installed on your Matrix computer. If an agent is missing, clicking it opens a new shell tab and runs the npm installer there so you can watch the output.

The install command that runs is:

export MATRIX_NODE_PREFIX="${MATRIX_NODE_PREFIX:-/opt/matrix/runtime/node}"
npm install -g --prefix "$MATRIX_NODE_PREFIX" <package>

Each agent maps to an npm package:

Agent	Package
Claude Code	`@anthropic-ai/claude-code@latest`
Codex	`@openai/codex@latest`
OpenCode	`opencode-ai@latest`
Pi	`@earendil-works/pi-coding-agent@latest`

The default node prefix is /opt/matrix/runtime/node. Set MATRIX_NODE_PREFIX in your environment to use a different location.

Claude Code quick start

Open Terminal, click +, and select Claude Code. If it is not installed yet, Matrix opens a visible installer tab. Wait for it to finish, then select Claude Code again.

Complete Claude Code's own browser login in the terminal. Keep account credentials in that provider-owned login flow.

Start a new named Claude Code session for your project. It keeps running on the Matrix computer when you disconnect.

Let a local agent operate Matrix

On your local computer, install the public Matrix OS pack when you want an agent to connect to Matrix through the CLI. Matrix's website delegates to the pinned skills.sh CLI and installs all three focused skills globally for detected agents:

curl -fsSL https://matrix-os.com/install/skills | sh

Start a new Codex, Claude Code, OpenCode, or Pi session afterward. The pack installs matrix-onboarding, matrix-cloud-run, and matrix-github-project: setup/recovery, observable cloud work, and safe GitHub checkout workflows. The separate 19-skill pack already available inside a Matrix computer teaches agents how to build and use Matrix apps.

Skills teach workflows; MCP supplies executable tools. The Matrix OS plugin's hosted configuration connects to the same HTTP endpoint described below. Installing skills alone does not configure an MCP connection. The stdio alternative uses the Matrix CLI and its separate cloud login.

To move an active local repository and task context into Matrix, install and use the separate matrix-handoff skill. It previews an exact upload scope and requires a matching approval token before transferring anything. See Hand off an active task to Matrix.

See Matrix Skills for the three skill sets, a one-command install across all four agents, and how Agent Skills differ from AGENTS.md project instructions. OpenCode and Pi also document their native skill support in the OpenCode skills guide and Pi skills guide.

Connect a local agent over MCP

Use the separately authenticated stdio alternative while hosted MCP is disabled. After hosted rollout, connect over Streamable HTTP directly or through the Matrix OS plugin. See Matrix MCP: install and connect for client setup, browser OAuth, rollout status, and a first test.

Running an agent

Open Terminal in the web shell.

Click the + button to open the new-session menu.

Select the agent you want to run. If it is installed, a new tab opens running the agent. If it is not installed, a new tab opens running the installer instead.

From the CLI

Use matrix run -it to start an agent in a named shell session. Named sessions keep working after you disconnect.

matrix run -it --session main -- claude
matrix run -it --session main -- codex
matrix run -it --session main -- opencode
matrix run -it --session main -- pi

Or connect to an existing session and run the agent manually:

matrix shell connect -c main
cd ~/projects/my-repo
claude

See CLI reference for matrix run and matrix shell connect options, and Shell for how named sessions work across devices.

Generated files in Chat

When a coding agent produces a supported local artifact, Matrix saves it with the Chat conversation. Generated images appear beside the assistant's reply. During image generation, a placeholder shows that the image is still in progress; after the file is ready, select its thumbnail to view it at full size or choose File Preview to inspect the saved file. Local file links in a reply can also open File Preview. Links from a project run retain the project and worktree where the run happened.

File Preview displays images, PDFs, text and Markdown, CSV and TSV tables, audio, video, and isolated static HTML when the file type can be verified. Other formats show a file card with a download option. Office documents, HEIC conversion, remote media links, SVG rendering, and archive extraction are not yet supported as rich previews.

The file remains in your Matrix computer's owner-controlled storage. Preview access follows the same account and project permissions as file access; a link alone does not grant another person permission to read it. Native Mobile support is still in development.

Approvals and connector requests in Chat

When you use a coding agent through Matrix Chat, a simple task can pause while the agent waits for permission or a response. Waiting for your approval or Waiting for your response is different from active model work. Review the pending request in the conversation before retrying the task.

Connector requests may ask for a choice, a short form, or authorization in an external browser page. Choose Allow once only after reviewing the request. Use Decline or Cancel if you do not want to continue; you do not need to fill required fields to decline or cancel. Nothing is selected or submitted automatically, and allowing one request does not create a permanent grant.

For browser authorization, check the displayed destination before opening it. Complete the connector's own authorization flow, then return to Chat to confirm. Opening the link alone does not submit your response. Do not paste account credentials into a conversation.

Unanswered requests expire after about five minutes and are cancelled, not approved. Unsupported connector forms fail closed. If a run appears stuck, check for a pending request before sending the same task again: switching from polling to streaming by itself does not resolve a missing permission response.

Runtime and client updates

These controls require the updated Matrix runtime and Chat client. If your version shows only a spinner instead of a pending request, update both and retry the task. Terminal-launched agents continue to use their own interfaces.

Agent credentials

Each agent requires its own credentials. Sign in through the agent's own CLI flow after the install completes — for example claude prompts for Anthropic account login, and codex and opencode require an API key or provider login.

Keep credentials out of chat and logs

Sign in to each coding agent only through its own supported CLI flow. Do not paste API keys into chats, documents, or terminal output that may be shared or logged.

Matrix skills for agents

Matrix OS syncs a curated skill pack into each agent's skill discovery path at install time. The skills teach agents how to build Matrix apps, use the shell design system, and navigate the project layout. They are stored under ~/agents/skills/ on your Matrix computer and updated when you run matrix sync.