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 skill when you want an agent to connect to Matrix through the CLI. Run the matching skills.sh CLI command from your local project root, then start a new agent session:

# Claude Code
npx skills add HamedMP/matrix-os --skill matrix-os --agent claude-code

# Codex
npx skills add HamedMP/matrix-os --skill matrix-os --agent codex

# OpenCode
npx skills add HamedMP/matrix-os --skill matrix-os --agent opencode

# Pi
npx skills add HamedMP/matrix-os --skill matrix-os --agent pi

This local skill teaches the agent to install and use the Matrix CLI, sign in, verify your computer, and start observable remote sessions. The separate skill pack already available inside a Matrix computer teaches agents how to build and use Matrix apps.

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.

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.

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.