Your agents. One surface. Local-first.
Matrix is a local communication hub for coding agents. It connects people, scripts and supervisory agents to existing ACP or A2A agents, and keeps their runs, session identities and project state in one place.
Use OpenCode to implement a change, ask another specialist to review it, or submit a task from a supervisor and wait for a completion or intervention event. The agents execute the work; Matrix routes requests, maintains continuity and makes the outcome inspectable.
Get started · Wiki · Releases · API
Experimental software. Commands, APIs and integration contracts can change. Check provider capabilities and release notes before depending on a workflow.
An agent is the tool or harness, such as OpenCode or Codex through its ACP adapter. A model is the backend that agent uses. Matrix can request a model where the protocol supports it; credentials, subscriptions and inference stay with the provider.
Matrix runs on Linux, macOS and Windows through a platform abstraction layer (PAL). It stores its runtime state under one OS-native application home. An agent or model service can still be remote: local-first describes Matrix's control and state, not where every prompt is processed.
| Need | Matrix provides |
|---|---|
| Reach several agents from one place | Telegram, authenticated HTTP, CLI and protocol adapters into a common routing core |
| Keep work attached to a project | Explicit workspace roots, session bindings, timeline, work memory and state snapshots |
| Continue or import an existing conversation | Distinct logical and provider session IDs; capability-gated load, resume, discovery and fork |
| Move work to another specialist | A recorded handoff brief delivered on the destination's next turn |
| Delegate without watching every token | Async runs, run events, input requests, cancellation and durable local notifications on Linux/macOS |
| Attach supervisory context | Sidecar capsules with delivery traces, separate from normal chat text |
| Understand a failure | Run traces, requested/effective model information, stall views and typed recovery outcomes |
| Control execution resources | Optional provider permissions, Docker isolation and runtime admission based on concurrency and workspace disk capacity |
| Inspect or export operational state | Read-only semantic filesystem, optional native mount, local logs and optional bounded OTLP/HTTP log export |
Matrix exposes coordination primitives. Your supervisor or application defines its workflow, parallelism and review policy. Provider features are negotiated; an unsupported resume or fork is reported rather than simulated.
The same core supports four communication patterns:
| Pattern | Example |
|---|---|
| Human to agent | A developer sends a task from Telegram or HTTP |
| Agent to agent | A supervisor delegates to a specialist through Matrix |
| One to many | One caller submits separate runs to several specialists |
| Many to many | Several callers and agents coordinate through explicit run/session/workspace bindings |
You need an installed, authenticated agent with a compatible adapter, or a configured remote A2A endpoint. Matrix can discover and install registry agents; installing Matrix alone does not configure a model account.
Linux / macOS — download the installer for one resolved version, inspect it, then run it:
MATRIX_VERSION="$(curl -fsSL https://api.github.com/repos/Josepavese/matrix/releases/latest | sed -n 's/.*"tag_name": "\(v[^"]*\)".*/\1/p' | head -n 1)"
curl -fsSLO "https://github.com/Josepavese/matrix/releases/download/${MATRIX_VERSION}/install.sh"
less install.sh
env MATRIX_VERSION="$MATRIX_VERSION" sh install.shWindows PowerShell:
$release = Invoke-RestMethod https://api.github.com/repos/Josepavese/matrix/releases/latest
$env:MATRIX_VERSION = $release.tag_name
Invoke-WebRequest "https://github.com/Josepavese/matrix/releases/download/$env:MATRIX_VERSION/install.ps1" -OutFile install.ps1
notepad install.ps1
.\install.ps1For repeatable installs, use an explicit vX.Y.Z. No repository clone is needed.
This example uses an already working OpenCode installation. Replace its ID and path with your setup:
matrix bootstrap doctor
matrix agent list
matrix agent doctor opencode
matrix workspace add my-project --path /absolute/path/to/project --default-agent opencode
matrix runmatrix run stays in the foreground. If Matrix already runs as a service, use
that instance. Bootstrap doctor reports setup guidance; it does not sign into
providers. See agent setup.
The daemon generates an HTTP key on startup. This Bash example loads it locally and names the project explicitly:
MATRIX_API_KEY="$(matrix config get matrix_api_key)"
curl --fail-with-body -sS http://127.0.0.1:9091/v1/runs \
-H "X-Matrix-Key: $MATRIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"channel_id": "docs.http",
"agent_id": "opencode",
"workspace_id": "my-project",
"execution_mode": "sync",
"input": "Explain this project. Read files as needed; do not modify them."
}'The instruction above is a task request, not an enforced read-only sandbox. Getting Started also includes a PowerShell request.
For example, submit a repository review with execution_mode: "async", retain
its run_id, and consume events instead of feeding the whole transcript into
the supervisor's context. On Linux/macOS, matrix run wait <run-id> reads the
private notification socket. Supervisors can listen directly for input requests
and terminal outcomes, persist a cursor, and acknowledge delivery.
Windows clients use the HTTP run event stream and elicitation API; the Unix notification socket and its wait/ack commands are not available there. Delegation and Notifications explains the delivery guarantees and runnable requests.
The shipped seed definitions include OpenCode, Gemini CLI, Claude Code's ACP adapter and Kimi. Codex has a dedicated ACP installation and launch contract. MiMo Code can be registered as an ACP agent and has a native permission contract. Registry entries and your local configuration determine which agents are installed and enabled.
The ecosystem below follows Zed’s ACP agent directory. Matrix connects through the agent’s native ACP support or its adapter; install, authentication and available session/model operations depend on that integration.
Browse agents with matrix agent search and inspect your installation with
matrix agent doctor <id>. This is an ecosystem directory, not a claim that
all entries have passed Matrix end-to-end qualification. Icon sources.
- ACP: managed stdio agents and configured external transports; session and model operations depend on advertised capabilities.
- A2A: remote agent registration, protocol bindings and task communication.
- Agent-to-agent workflows: callers use the same run and session surfaces as other clients. Matrix does not need a separate model subscription to route them.
See Using Agents and the protocol coverage for exact support and limits.
- Provider permissions and OS isolation are distinct. OpenCode/MiMo policies are configured, not attested. Optional Docker isolation requires a prepared local Linux image and explicit workspace/state/resource settings.
- Capacity is host capacity. Admission limits cover this Matrix runtime and volume reservations are bookkeeping; they are not disk quotas or provider credits.
- State views are selective. The semantic filesystem exposes agent, run and workspace state, not project files or a semantic search engine. Summaries are an explicit CLI/mount opt-in; HTTP views exclude them.
- Export is optional. The OTLP collector receives selected operational logs, not prompt/transcript content or billing data. Local logs remain primary.
- Local storage needs protection. Vault encryption uses a configured master key; local-first alone does not mean encrypted. HTTP authentication and Telegram administrator controls are enforced by default.
Native PAL contracts are tested on Linux, Windows and macOS. Real container and FUSE qualification is recorded for Linux; Windows/macOS Docker and mount drivers still require qualification in the intended environment. See the PAL guide and v0.1.53 evidence.
The versioned Wiki lives in this repository alongside the code. Start with a task, then follow the relevant guide:
| Start here | Go deeper |
|---|---|
| Getting Started | Installation, agent readiness and first prompt |
| Core Concepts | Agents, models, runs, sessions, workspaces and channels |
| Delegation and Notifications | Async work, wakeups, cursors and intervention |
| Sessions and Recovery | External import, strict identity and interrupted runs |
| Handoff / Sidecar Capsules | Specialist briefs and supervisory context |
| Workspaces / Channels | Project state, Telegram, HTTP and CLI |
| PAL Execution and Observability | Sandbox, capacity, semantic filesystem and collector |
| CLI Reference / API Reference | Commands and wire contracts |
| Examples / FAQ | Workflows, limits and troubleshooting |
- Contribution guide, test guide and quality gates.
- Governance, release runbook and security policy.
- Product thesis and roadmap describe direction; they are not a list of shipped capabilities.
Licensed under Apache-2.0.