Experimental warning: Matrix is in an experimental testing phase. Public APIs, commands, install behavior, and integrations may change between releases. Use it for evaluation and local workflows, not as a stable production contract.
Your agents. One surface. Local-first.
Talk to Claude, Gemini, OpenCode, and any ACP/A2A agent from Telegram, HTTP, or CLI.
Human to agent. One to many. Agent to agent. Many to many.
You use more than one coding agent. Claude for reasoning. Gemini for speed. OpenCode for open-source work. Each has its own CLI, its own sessions, its own context. There is no way to hand off work between them. No shared memory. No continuity.
Matrix fixes this. It is a local-first daemon that sits between you and your agents, giving you one communication surface for all of them.
One prompt, any agent -- send a message, Matrix routes it to the right agent.
curl -X POST http://127.0.0.1:9091/v1/runs \
-H "Content-Type: application/json" \
-d '{
"channel_id": "docs.http",
"input": "Explain this function"
}'Hand off without losing context -- transfer work from one agent to another mid-session.
/handoff claude
Workspaces that remember -- bind conversations to projects. Get timelines, memory, and snapshots.
/use billing-api
/timeline
/snapshot before-refactor
Talk from anywhere -- Telegram, HTTP API, CLI. Same sessions. Same workspaces. Same state.
Let agents talk to agents -- Matrix can be used as a tool by supervisory AIs or coding agents to route work to one agent, many agents, or other agent groups without binding to one protocol.
Install without cloning the repo.
Linux / macOS:
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.sh
matrix bootstrap doctor
matrix runFor automation, pin the release explicitly:
MATRIX_VERSION=vX.Y.Z
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.ps1
matrix bootstrap doctor
matrix runPinned install:
$env:MATRIX_VERSION = "vX.Y.Z"
Invoke-WebRequest "https://github.com/Josepavese/matrix/releases/download/$env:MATRIX_VERSION/install.ps1" -OutFile install.ps1
notepad install.ps1
.\install.ps1Prerequisites: at least one coding agent installed (OpenCode, Claude Code, or Gemini CLI). Matrix routes to your agents -- it does not replace them.
Send your first prompt:
curl -X POST http://127.0.0.1:9091/v1/runs \
-H "Content-Type: application/json" \
-d '{
"channel_id": "docs.http",
"input": "What files are in the current directory?"
}'| Agent | Command | Status |
|---|---|---|
| OpenCode | opencode acp |
Active by default |
| Gemini CLI | gemini --acp |
Active |
| Claude Code | claude-agent-acp |
Available |
| Kimi | kimi acp |
Available |
Any agent that speaks ACP or A2A works. Search and install more with matrix agent search.
Protocol note: Matrix follows Zed ACP for ACP agents. ACP branch work uses real
capability-gated session/fork; there is no ACP side primitive. Matrix
sidecar capsules are Matrix-level context, projected into ACP/A2A without
polluting normal chat.
- A human, channel, agent, or supervisory AI enters through Telegram, HTTP, CLI, ACP, or A2A
- Matrix resolves workspace, session, intent, protocol, and target agent set
- Work is routed one-to-one, one-to-many, agent-to-agent, or many-to-many
- Results flow back. Everything is logged in the workspace timeline.
Matrix is built for this cycle:
- Implement -- send a prompt, let the agent work
- Review --
/reviewto switch into review mode - Hand off --
/handoff claudeto pass work to another agent - Snapshot --
/snapshot before-deployto save state - Resume --
/continueor/resumeto pick up later
| Matrix | Agent frameworks | Chat wrappers | Protocol gateways | |
|---|---|---|---|---|
| Uses your existing agents | Yes | No (builds new ones) | Sometimes | Sometimes |
| Agent-to-agent handoff | Yes | Rarely | No | No |
| One-to-many and many-to-many routing | Yes | Sometimes | No | Rarely |
| Workspace memory and timeline | Yes | No | No | No |
| Cross-channel continuity | Yes | No | No | No |
| Local-first with encryption | Yes | Varies | No | Varies |
| Protocol-agnostic | Yes (ACP + A2A) | Usually one | No | Usually one |
The Matrix Wiki is the developer guide. It covers everything you need to get productive:
- Getting Started -- install, configure, first prompt
- Core Concepts -- workspaces, sessions, agents, channels explained
- Using Agents -- search, install, configure, and switch agents
- Handoff -- transfer work between agents with context
- Sidecar Capsules -- attach machine-trackable supervisor context to runs
- Workspaces -- timelines, memory, snapshots, decisions
- Channels -- Telegram, HTTP API, CLI setup
- API Reference -- every endpoint with examples
- CLI Reference -- every command documented
- Governance -- release gates and maintainer invariants
- Examples -- step-by-step workflows
- FAQ -- common questions and troubleshooting
For contributors and those interested in the product direction:
- Product profile
- Category thesis
- Product roadmap
- Chat UX spec
- Workspace affinity spec
- Workspace timeline spec
- Protocol-neutral runtime
- Orchestration surface
- Decision trace spec
- Run trace spec
- Installation guide
- Timeout and recovery
- Production readiness
- Deployment policy
- Governance
- Threat model
- Brand direction
- Developers using more than one coding agent
- Teams tired of agent sprawl and context loss
- AI-native workflows that need a local communication layer
- Supervisory AI systems that need a reliable routing substrate
- Tone: sharp, operator-first, technical, controlled
- Primary:
#0B1020#00D1B2#3B82F6#F5F7FB - Accent:
#FF7A59#A3E635