Work on GitHub Projects in Matrix OS

Authenticate and inspect everything on the Matrix VPS, preserve existing work, and push or open a PR only when explicitly requested. Prefer hosted Matrix MCP tools with the client's browser OAuth flow. Keep the separately authenticated CLI fallback optional.

MCP-first execution

1. Call list_computers and target one explicit runtimeSlot for every operation.
2. Use run_command with its command argv array for repository probes and short work that needs captured output. Hosted HTTP defaults to and caps commands at 45 seconds; run longer Git operations and tests in persistent terminals.
3. Use create_terminal, create_terminal_tab, select_terminal_tab, and send_terminal_input for long-running or user-observable work. Report the terminal/tab identity.
4. Use bounded file tools only for Matrix-home content; never move local credentials or accept arbitrary local paths.
5. Use read-only chat tools when a prior Matrix chat is necessary to recover project context.

If HTTP MCP authentication fails, use codex mcp login <configured-server-name> or Claude Code's /mcp browser authentication. matrix login repairs only stdio/CLI login. If hosted tools are absent or unavailable, offer the CLI fallback explicitly; never copy credentials between transports.

CLI fallback terminal policy

• Always run remote work with matrix run -it --project <project> ... -- <argv...>; use main before a project exists.
• Create a separate tab in the project workspace for every additional command, terminal, or concurrent task.
• Report every returned tab ID and its matrix shell connect --project <project> --tab <tab-id> command.
• Pass arguments after --; never interpolate user input into a shell string.

CLI fallback readiness gate

Verify the local CLI, hosted profile, login, identity, and instance before touching a checkout:

matrix --version
matrix profile show cloud
matrix doctor
matrix whoami
matrix status
matrix instance info --json

If matrix instance info reports ready: true with source: execution_probe, continue and report that the management plane is degraded. Stop only when both management and execution checks fail.

If needed, run matrix login --profile cloud and let the user complete browser/device authentication. Wait for provisioning at https://app.matrix-os.com when no ready computer exists.

Check only the selected coding agent on Matrix, using a separate tab for each check:

matrix run -it --project main -- codex --version
matrix run -it --project main -- codex login status
matrix run -it --project main -- claude --version
matrix run -it --project main -- claude auth status

Run only the Codex pair or Claude pair. Authenticate a disconnected agent in auth-codex-<suffix> or auth-claude-<suffix>. Never scan, read, or upload local credential files. If an agent is missing, ask before installing a global tool and prefer Matrix's visible developer-tool installation path.

GitHub authentication must also live on Matrix:

matrix run -it --project main -- gh --version
matrix run -it --project main -- gh auth status
matrix run -it --project main -- gh auth login --hostname github.com --git-protocol ssh --web
matrix shell connect --project main --tab <tab-id>

Use the login session only when needed, then re-run remote gh auth status in a new session. If gh is missing, ask before installing it globally and prefer Matrix's visible developer-tool installation path. Do not rely on the local computer's GitHub login.

Resolve the repository and destination

1. Parse the requested GitHub URL or owner/repo identifier and normalize it to a lowercase GitHub owner/repository pair with any .git suffix removed.
2. Default ordinary repositories to projects/<repo>. Use apps/<slug> only when the checkout should run directly as a Matrix app.
3. Validate a safe relative destination under the Matrix home. Reject absolute paths, backslashes, control characters, and . or .. segments.
4. Inspect the destination before using -C.

Probe the destination in separate tabs:

matrix run -it --project main -- test -e projects/<repo>
matrix run -it --project main -- test -d projects/<repo>
matrix run -it --project main -- ls -la projects/<repo>

If the destination is absent, clone it with remote GitHub CLI:

matrix run -it --project main -- gh repo clone <owner>/<repo> projects/<repo>
matrix shell connect --project main --tab <tab-id>

If the destination exists:

• Stop on a non-Git directory collision.
• Read git remote get-url origin and derive its normalized GitHub owner/repository.
• Reuse the checkout only when that normalized owner/repository exactly matches the request.
• Stop on a mismatched origin; never repoint it automatically.

Preserve the checkout

Before fetching, switching, installing, launching an agent, or editing, inspect the branch and dirty state in separate project tabs:

matrix run -it --project <repo> -C <dir> -- git status --porcelain=v1 --branch
matrix run -it --project <repo> -C <dir> -- git branch --show-current
matrix run -it --project <repo> -C <dir> -- git remote get-url origin

Treat staged, unstaged, untracked, rebasing, merging, and detached states as meaningful user work. Never reset, clean, stash, or overwrite user changes automatically. If the checkout is dirty or mid-operation, stop and ask whether to continue on the current state, finish the operation, or choose a separate clean checkout.

For a clean new task, follow repository instructions and the user's branch preference. If no branch is specified, resolve the remote default branch with gh repo view, fetch it, and create matrix/<task-slug> from the remote default branch. Stop if the target branch already exists rather than overwriting it.

Understand and change the project

Read repository instructions before choosing commands:

• AGENTS.md, CLAUDE.md, or equivalent repository instructions, including nested files for the target area.
• README files and contributing guidance.
• Package-manager lockfiles and task scripts.
• Environment examples such as .env.example; never read secret environment files unless the user explicitly authorizes a specific read.
• Build, test, and development documentation.

Use a separate tab for the coding task. For unattended Codex changes:

matrix run -it --project <repo> -C <dir> -- codex --ask-for-approval never --sandbox workspace-write exec -- <prompt>
matrix shell connect --project <repo> --tab <tab-id>

Use --sandbox read-only for inspection. Never use danger-full-access without explicit direction.

Run Claude without repetitive permission questions using its verified auto mode:

matrix run -it --project <repo> -C <dir> -- claude --permission-mode auto -p <prompt>
matrix shell connect --project <repo> --tab <tab-id>

If Claude auto mode is unavailable, report that limitation and stop; do not fall back to a permission bypass.

Run relevant validation in new tabs. Do not install dependencies until the package manager, lockfile, and dirty state are understood. Push or open a PR only when explicitly requested.

Handoff

Report the normalized repository, checkout path, branch, starting dirty state, changed files, validation commands and results, every running terminal reference, and every matrix shell connect --project <project> --tab <tab-id> reattach instruction. State clearly whether anything was pushed or published.