https://github.com/josepavese/matrix
Local-first agent communication matrix for Claude, Gemini, OpenCode and ACP/A2A agents: multi-agent orchestration, agent-to-agent handoff, workspace memory, Telegram, HTTP and CLI routing.
https://github.com/josepavese/matrix
a2a acp agent-client-protocol agent-orchestration agent-to-agent agent-to-agent-protocol ai-agents ai-coding claude coding-agents developer-tools gemini golang llm llmops local-first multi-agent opencode telegram-bot workflow-automation
Last synced: 22 days ago
JSON representation
Local-first agent communication matrix for Claude, Gemini, OpenCode and ACP/A2A agents: multi-agent orchestration, agent-to-agent handoff, workspace memory, Telegram, HTTP and CLI routing.
- Host: GitHub
- URL: https://github.com/josepavese/matrix
- Owner: Josepavese
- License: apache-2.0
- Created: 2026-02-27T08:56:32.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-07-15T11:08:30.000Z (26 days ago)
- Last Synced: 2026-07-15T12:13:00.305Z (26 days ago)
- Topics: a2a, acp, agent-client-protocol, agent-orchestration, agent-to-agent, agent-to-agent-protocol, ai-agents, ai-coding, claude, coding-agents, developer-tools, gemini, golang, llm, llmops, local-first, multi-agent, opencode, telegram-bot, workflow-automation
- Language: Go
- Size: 31.1 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Governance: docs/governance/README.md
Awesome Lists containing this project
README
> **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.
Matrix
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.
---
## The Problem
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.
## What You Get
**One prompt, any agent** -- send a message, Matrix routes it to the right agent.
```bash
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.
## Quick Start
Install without cloning the repo.
**Linux / macOS:**
```bash
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 run
```
For automation, pin the release explicitly:
```bash
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.sh
```
**Windows PowerShell:**
```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 run
```
Pinned install:
```powershell
$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.ps1
```
Prerequisites: 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:**
```bash
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?"
}'
```
## Supported Agents
| 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.
## How It Works
1. A human, channel, agent, or supervisory AI enters through Telegram, HTTP, CLI, ACP, or A2A
2. Matrix resolves workspace, session, intent, protocol, and target agent set
3. Work is routed one-to-one, one-to-many, agent-to-agent, or many-to-many
4. Results flow back. Everything is logged in the workspace timeline.
## The Operator Loop
Matrix is built for this cycle:
1. **Implement** -- send a prompt, let the agent work
2. **Review** -- `/review` to switch into review mode
3. **Hand off** -- `/handoff claude` to pass work to another agent
4. **Snapshot** -- `/snapshot before-deploy` to save state
5. **Resume** -- `/continue` or `/resume` to pick up later
## What Makes Matrix Different
| | 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 |
## Documentation
### Wiki (start here)
The [Matrix Wiki](docs/wiki/Home.md) is the developer guide. It covers everything you need to get productive:
- [Getting Started](docs/wiki/Getting-Started.md) -- install, configure, first prompt
- [Core Concepts](docs/wiki/Core-Concepts.md) -- workspaces, sessions, agents, channels explained
- [Using Agents](docs/wiki/Using-Agents.md) -- search, install, configure, and switch agents
- [Handoff](docs/wiki/Handoff.md) -- transfer work between agents with context
- [Sidecar Capsules](docs/wiki/Sidecar-Capsules.md) -- attach machine-trackable supervisor context to runs
- [Workspaces](docs/wiki/Workspaces.md) -- timelines, memory, snapshots, decisions
- [Channels](docs/wiki/Channels.md) -- Telegram, HTTP API, CLI setup
- [API Reference](docs/wiki/API-Reference.md) -- every endpoint with examples
- [CLI Reference](docs/wiki/CLI-Reference.md) -- every command documented
- [Governance](docs/wiki/Governance.md) -- release gates and maintainer invariants
- [Examples](docs/wiki/Examples.md) -- step-by-step workflows
- [FAQ](docs/wiki/FAQ.md) -- common questions and troubleshooting
### Product and Design Docs
For contributors and those interested in the product direction:
- [Product profile](PRODUCT.md)
- [Category thesis](docs/matrix_category_thesis.md)
- [Product roadmap](docs/matrix_product_roadmap_2026_2027.md)
- [Chat UX spec](docs/matrix_chat_ux_spec.md)
- [Workspace affinity spec](docs/matrix_workspace_affinity_spec.md)
- [Workspace timeline spec](docs/matrix_workspace_timeline_spec.md)
- [Protocol-neutral runtime](docs/matrix_protocol_neutral_runtime.md)
- [Orchestration surface](docs/matrix_orchestration_surface_spec.md)
- [Decision trace spec](docs/matrix_decision_trace_spec.md)
- [Run trace spec](docs/matrix_agent_communication_run_trace.md)
- [Installation guide](docs/matrix_installation.md)
- [Timeout and recovery](docs/matrix_timeout_recovery_policy.md)
- [Production readiness](docs/matrix_production_readiness.md)
- [Deployment policy](docs/matrix_deployment_policy.md)
- [Governance](docs/governance/README.md)
- [Threat model](docs/matrix_threat_model.md)
- [Brand direction](docs/brand_direction.md)
### Project Metadata
- [License](LICENSE)
- [Security policy](SECURITY.md)
- [Contributing](CONTRIBUTING.md)
## Built For
- 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
## Visual Direction
- **Tone:** sharp, operator-first, technical, controlled
- **Primary:** `#0B1020` `#00D1B2` `#3B82F6` `#F5F7FB`
- **Accent:** `#FF7A59` `#A3E635`