{"id":51508485,"url":"https://github.com/josepavese/matrix","last_synced_at":"2026-07-19T10:00:56.502Z","repository":{"id":365689700,"uuid":"1168322265","full_name":"Josepavese/matrix","owner":"Josepavese","description":"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.","archived":false,"fork":false,"pushed_at":"2026-07-15T11:08:30.000Z","size":32582,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-15T12:13:00.305Z","etag":null,"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"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Josepavese.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":"docs/governance/README.md","roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-27T08:56:32.000Z","updated_at":"2026-07-15T10:49:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Josepavese/matrix","commit_stats":null,"previous_names":["josepavese/matrix"],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/Josepavese/matrix","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Josepavese%2Fmatrix","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Josepavese%2Fmatrix/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Josepavese%2Fmatrix/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Josepavese%2Fmatrix/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Josepavese","download_url":"https://codeload.github.com/Josepavese/matrix/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Josepavese%2Fmatrix/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35649100,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-19T02:00:06.923Z","response_time":112,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["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"],"created_at":"2026-07-08T03:30:26.310Z","updated_at":"2026-07-19T10:00:56.496Z","avatar_url":"https://github.com/Josepavese.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003e **Experimental warning:** Matrix is in an experimental testing phase. Public\n\u003e APIs, commands, install behavior, and integrations may change between releases.\n\u003e Use it for evaluation and local workflows, not as a stable production contract.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/readme/hero.png\" alt=\"Matrix\" width=\"1000\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eMatrix\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eYour agents. One surface. Local-first.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  Talk to Claude, Gemini, OpenCode, and any ACP/A2A agent from Telegram, HTTP, or CLI.\u003cbr/\u003e\n  Human to agent. One to many. Agent to agent. Many to many.\n\u003c/p\u003e\n\n---\n\n## The Problem\n\nYou 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.\n\n**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.\n\n## What You Get\n\n**One prompt, any agent** -- send a message, Matrix routes it to the right agent.\n\n```bash\ncurl -X POST http://127.0.0.1:9091/v1/runs \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"channel_id\": \"docs.http\",\n    \"input\": \"Explain this function\"\n  }'\n```\n\n**Hand off without losing context** -- transfer work from one agent to another mid-session.\n\n```\n/handoff claude\n```\n\n**Workspaces that remember** -- bind conversations to projects. Get timelines, memory, and snapshots.\n\n```\n/use billing-api\n/timeline\n/snapshot before-refactor\n```\n\n**Talk from anywhere** -- Telegram, HTTP API, CLI. Same sessions. Same workspaces. Same state.\n\n**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.\n\n## Quick Start\n\nInstall without cloning the repo.\n\n**Linux / macOS:**\n\n```bash\nMATRIX_VERSION=\"$(curl -fsSL https://api.github.com/repos/Josepavese/matrix/releases/latest | sed -n 's/.*\"tag_name\": \"\\(v[^\"]*\\)\".*/\\1/p' | head -n 1)\"\ncurl -fsSLO \"https://github.com/Josepavese/matrix/releases/download/${MATRIX_VERSION}/install.sh\"\nless install.sh\nenv MATRIX_VERSION=\"$MATRIX_VERSION\" sh install.sh\nmatrix bootstrap doctor\nmatrix run\n```\n\nFor automation, pin the release explicitly:\n\n```bash\nMATRIX_VERSION=vX.Y.Z\ncurl -fsSLO \"https://github.com/Josepavese/matrix/releases/download/${MATRIX_VERSION}/install.sh\"\nless install.sh\nenv MATRIX_VERSION=\"$MATRIX_VERSION\" sh install.sh\n```\n\n**Windows PowerShell:**\n\n```powershell\n$release = Invoke-RestMethod https://api.github.com/repos/Josepavese/matrix/releases/latest\n$env:MATRIX_VERSION = $release.tag_name\nInvoke-WebRequest \"https://github.com/Josepavese/matrix/releases/download/$env:MATRIX_VERSION/install.ps1\" -OutFile install.ps1\nnotepad install.ps1\n.\\install.ps1\nmatrix bootstrap doctor\nmatrix run\n```\n\nPinned install:\n\n```powershell\n$env:MATRIX_VERSION = \"vX.Y.Z\"\nInvoke-WebRequest \"https://github.com/Josepavese/matrix/releases/download/$env:MATRIX_VERSION/install.ps1\" -OutFile install.ps1\nnotepad install.ps1\n.\\install.ps1\n```\n\nPrerequisites: at least one coding agent installed (OpenCode, Claude Code, or Gemini CLI). Matrix routes to your agents -- it does not replace them.\n\n**Send your first prompt:**\n\n```bash\ncurl -X POST http://127.0.0.1:9091/v1/runs \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"channel_id\": \"docs.http\",\n    \"input\": \"What files are in the current directory?\"\n  }'\n```\n\n## Supported Agents\n\n| Agent | Command | Status |\n|-------|---------|--------|\n| OpenCode | `opencode acp` | Active by default |\n| Gemini CLI | `gemini --acp` | Active |\n| Claude Code | `claude-agent-acp` | Available |\n| Kimi | `kimi acp` | Available |\n\nAny agent that speaks ACP or A2A works. Search and install more with `matrix agent search`.\n\nProtocol note: Matrix follows Zed ACP for ACP agents. ACP branch work uses real\ncapability-gated `session/fork`; there is no ACP `side` primitive. Matrix\nsidecar capsules are Matrix-level context, projected into ACP/A2A without\npolluting normal chat.\n\n## How It Works\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/readme/workflow.png\" alt=\"How Matrix routes work\" width=\"1000\" /\u003e\n\u003c/p\u003e\n\n1. A human, channel, agent, or supervisory AI enters through Telegram, HTTP, CLI, ACP, or A2A\n2. Matrix resolves workspace, session, intent, protocol, and target agent set\n3. Work is routed one-to-one, one-to-many, agent-to-agent, or many-to-many\n4. Results flow back. Everything is logged in the workspace timeline.\n\n## The Operator Loop\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/readme/operator-loop.png\" alt=\"The Matrix operator loop\" width=\"1000\" /\u003e\n\u003c/p\u003e\n\nMatrix is built for this cycle:\n\n1. **Implement** -- send a prompt, let the agent work\n2. **Review** -- `/review` to switch into review mode\n3. **Hand off** -- `/handoff claude` to pass work to another agent\n4. **Snapshot** -- `/snapshot before-deploy` to save state\n5. **Resume** -- `/continue` or `/resume` to pick up later\n\n## What Makes Matrix Different\n\n| | Matrix | Agent frameworks | Chat wrappers | Protocol gateways |\n|---|---|---|---|---|\n| Uses your existing agents | Yes | No (builds new ones) | Sometimes | Sometimes |\n| Agent-to-agent handoff | Yes | Rarely | No | No |\n| One-to-many and many-to-many routing | Yes | Sometimes | No | Rarely |\n| Workspace memory and timeline | Yes | No | No | No |\n| Cross-channel continuity | Yes | No | No | No |\n| Local-first with encryption | Yes | Varies | No | Varies |\n| Protocol-agnostic | Yes (ACP + A2A) | Usually one | No | Usually one |\n\n## Documentation\n\n### Wiki (start here)\n\nThe [Matrix Wiki](docs/wiki/Home.md) is the developer guide. It covers everything you need to get productive:\n\n- [Getting Started](docs/wiki/Getting-Started.md) -- install, configure, first prompt\n- [Core Concepts](docs/wiki/Core-Concepts.md) -- workspaces, sessions, agents, channels explained\n- [Using Agents](docs/wiki/Using-Agents.md) -- search, install, configure, and switch agents\n- [Handoff](docs/wiki/Handoff.md) -- transfer work between agents with context\n- [Sidecar Capsules](docs/wiki/Sidecar-Capsules.md) -- attach machine-trackable supervisor context to runs\n- [Workspaces](docs/wiki/Workspaces.md) -- timelines, memory, snapshots, decisions\n- [Channels](docs/wiki/Channels.md) -- Telegram, HTTP API, CLI setup\n- [API Reference](docs/wiki/API-Reference.md) -- every endpoint with examples\n- [CLI Reference](docs/wiki/CLI-Reference.md) -- every command documented\n- [Governance](docs/wiki/Governance.md) -- release gates and maintainer invariants\n- [Examples](docs/wiki/Examples.md) -- step-by-step workflows\n- [FAQ](docs/wiki/FAQ.md) -- common questions and troubleshooting\n\n### Product and Design Docs\n\nFor contributors and those interested in the product direction:\n\n- [Product profile](PRODUCT.md)\n- [Category thesis](docs/matrix_category_thesis.md)\n- [Product roadmap](docs/matrix_product_roadmap_2026_2027.md)\n- [Chat UX spec](docs/matrix_chat_ux_spec.md)\n- [Workspace affinity spec](docs/matrix_workspace_affinity_spec.md)\n- [Workspace timeline spec](docs/matrix_workspace_timeline_spec.md)\n- [Protocol-neutral runtime](docs/matrix_protocol_neutral_runtime.md)\n- [Orchestration surface](docs/matrix_orchestration_surface_spec.md)\n- [Decision trace spec](docs/matrix_decision_trace_spec.md)\n- [Run trace spec](docs/matrix_agent_communication_run_trace.md)\n- [Installation guide](docs/matrix_installation.md)\n- [Timeout and recovery](docs/matrix_timeout_recovery_policy.md)\n- [Production readiness](docs/matrix_production_readiness.md)\n- [Deployment policy](docs/matrix_deployment_policy.md)\n- [Governance](docs/governance/README.md)\n- [Threat model](docs/matrix_threat_model.md)\n- [Brand direction](docs/brand_direction.md)\n\n### Project Metadata\n\n- [License](LICENSE)\n- [Security policy](SECURITY.md)\n- [Contributing](CONTRIBUTING.md)\n\n## Built For\n\n- Developers using more than one coding agent\n- Teams tired of agent sprawl and context loss\n- AI-native workflows that need a local communication layer\n- Supervisory AI systems that need a reliable routing substrate\n\n## Visual Direction\n\n- **Tone:** sharp, operator-first, technical, controlled\n- **Primary:** `#0B1020` `#00D1B2` `#3B82F6` `#F5F7FB`\n- **Accent:** `#FF7A59` `#A3E635`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjosepavese%2Fmatrix","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjosepavese%2Fmatrix","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjosepavese%2Fmatrix/lists"}