Developer Workflow

AI coding has moved from autocomplete to agents that can read repositories, edit files, run tests, open pull requests, and work in the background. Matrix OS gives those agents a persistent place to work: your own cloud computer, your files, your shell sessions, your project context, and your review history.

Use Matrix when you want the speed of Claude Code, Codex, Cursor, Copilot, Gemini CLI, Cline, Jules, Devin, or another agent without rebuilding your setup for every tool.

Quick Agent Setup

Paste this into Claude, Codex, Cursor, Cline, or another coding agent:

# Set Up Matrix OS For My Dev Workflow

Set up Matrix OS so I can use my own cloud computer for coding agents,
terminal sessions, and project work.

First, read the official Matrix agent skill:

```text
https://matrix-os.com/skills.md
```

If your runtime supports file skills, install it:

```bash
npx skills add HamedMP/matrix-os --skill matrix-os
```

Then show me this checklist:

1. Install or update the Matrix CLI
2. Run `matrix login` and wait for my Matrix instance to be ready
3. Start my preferred coding agent on Matrix with `matrix run`
4. Explain the reconnect and recovery commands only after the main path works

Then proceed step by step. Keep the happy path to two Matrix commands:

```bash
matrix login
matrix run -it -- claude
```

Use `codex`, `gemini`, or another terminal agent instead of `claude` if I ask for it.

## Step 1: Install or update the Matrix CLI

From the current project root, check whether the Matrix CLI is available:

```bash
command -v matrix && matrix --version
```

If `matrix` is missing, install it:

```bash
npm install -g @finnaai/matrix
```

If the user prefers another package manager, use the equivalent global
install command from `skills.md`.

## Step 2: Sign in to Matrix

Run:

```bash
matrix login
```

Pause while I complete the browser login flow. If Matrix says no instance
exists yet, send me to:

```text
https://app.matrix-os.com
```

Wait for provisioning, then run `matrix login` again.

## Step 3: Run agents inside Matrix

For a remote agent session, run one command at a time:

```bash
matrix run -it -- claude
```

or:

```bash
matrix run -it -- codex
```

Do not pre-create a named session and then run `matrix run --session` for
the first command. If a named session already exists, `matrix run --session`
may attach to it instead of launching the requested command.

## Step 4: Verify or recover only if needed

If setup fails, use:

```bash
matrix status
matrix doctor
matrix instance info
matrix shell ls
```

If I detach from a named setup session later, reconnect with:

```bash
matrix shell attach setup
```

## Step 5: Finish

Summarize:

- whether `matrix login` succeeded;
- whether the Matrix instance is ready;
- the exact command to start Claude, Codex, or my preferred agent in Matrix.

This pattern keeps the human in the login loop while still letting the coding agent do the install, verification, and setup work.

Why Matrix Helps

Most AI coding tools are optimized around one surface:

• an editor agent that edits the open project;
• a terminal agent that runs commands where you start it;
• a cloud task agent that clones a repository into a temporary environment;
• a pull request agent that works through GitHub issues or PRs.

Those surfaces are useful, but they fragment your workflow. Setup scripts, secrets, terminals, task notes, screenshots, logs, and review findings spread across machines and products.

Matrix gives you a stable home for the work:

• One always-on development machine - your Matrix instance keeps projects, terminals, files, and tools available after you close your laptop.
• Shared shell sessions - open a zellij session once, then reconnect from the web workspace, CLI, or an agent.
• Agent choice - run Claude Code, Codex CLI, Gemini CLI, Cline, or another terminal agent in the same environment.
• Durable context - keep repository notes, AGENTS.md, skills, task plans, transcripts, and review results where future agents can find them.
• Human control - agents can do the repetitive work, but you keep review, merge, deployment, and account decisions explicit.

Common AI Coding Workflows

Editor Pairing

Use this when you are actively reading code and want fast local edits.

Examples include Cursor Agent, GitHub Copilot agent mode, Windsurf Cascade, Cline in VS Code or JetBrains, and similar IDE agents. These tools are best for targeted refactors, UI iteration, "explain this code", and changing files while you stay in the editor.

Matrix adds value by keeping the remote shell, running services, test commands, and project state available even when the editor changes.

Terminal Agent Sessions

Use this when the agent needs to run commands, inspect the repo, install tools, execute tests, or drive a local browser.

Examples include Claude Code, Codex CLI, Gemini CLI, Cline CLI, and Devin for Terminal. Terminal agents pair naturally with Matrix because matrix run starts them on your Matrix instance from your local terminal.

npm i -g @finnaai/matrix
matrix login
matrix run -it -- claude

Use the agent you prefer:

matrix run -it -- codex
matrix run -it -- gemini

Async Cloud Tasks

Use this when the work is well-scoped and can run while you do something else.

Examples include Codex cloud tasks, GitHub Copilot coding agent, Google Jules, Devin cloud sessions, and other agents that open a draft pull request for review. These are good for dependency upgrades, documentation passes, test additions, simple bug fixes, and isolated feature slices.

Matrix adds value before and after the async work:

• prepare a clear task brief from your project context;
• keep setup commands and repository instructions in files;
• compare the agent PR against your local Matrix workspace;
• run follow-up checks in your persistent shell;
• hand the next round to another agent if the first one stalls.

Review And Repair Loops

Use this when code exists but needs hardening.

A strong loop is:

1. Ask one agent to implement the slice.
2. Run tests and pattern checks in Matrix.
3. Ask another agent or reviewer to inspect the diff.
4. Fix only actionable findings.
5. Repeat until the PR is boring.

This works especially well when Matrix keeps the terminal output, review notes, and source tree in one workspace instead of scattering them across separate browser tabs.

Recommended Matrix Setup

npm i -g @finnaai/matrix
matrix login
matrix whoami

What To Delegate

Prompt Pattern

Give agents the same shape of request each time:

Goal:
Fix the bug where ...

Context:
- The relevant files are ...
- The expected behavior is ...
- The current behavior is ...

Constraints:
- Do not change ...
- Keep data migration safe ...
- Use the existing pattern in ...

Verification:
- Run ...
- Add or update tests for ...
- Summarize remaining risk.

For bigger work, ask Matrix to turn a rough idea into a task brief first. Then give that brief to the agent that is best for the job.

How Matrix Fits With Popular Agents

Practical Weekly Workflow

1. Start the week in Matrix and ask for a project status summary.
2. Pick two or three small tasks that can become PRs.
3. Start the right agent with matrix run -it -- <agent>.
4. Let one agent implement while you use another for review or documentation.
5. Run tests and checks in Matrix before pushing.
6. Keep useful prompts, failures, and commands in the project so the next agent has better context.

Further Reading

• Claude Code docs
• OpenAI Codex docs
• Cursor docs
• GitHub Copilot coding agent docs
• Windsurf Cascade docs
• Gemini CLI docs
• Cline docs
• Jules docs
• Devin docs