#13013: feat(matrix): multi account support
channel: matrix
stale
Cluster:
Multi-Account Matrix Support
## Summary
Add multi-account support to the Matrix plugin, allowing multiple bot accounts to run simultaneously — each bound to a different agent via `bindings`. Follows the same patterns already used by Slack and Telegram.
## Changes
- **Config:** new `channels.matrix.accounts` map for per-account overrides
- **Routing:** pass `accountId` through monitor → handler → `resolveAgentRoute()` so bindings match correctly
- **Clients:** replace singleton client/credential stores with per-account `Map` registries
- **Credentials:** non-default accounts isolated under `credentials/matrix/accounts/{id}/`
- **DM policy:** `resolveDmPolicy` reads per-account config paths instead of hardcoded global path
- **Env vars:** `MATRIX_*` env vars scoped to default account only
22 files changed (+671 −241), all within `extensions/matrix/`.
Backward compatible — single-account configs (no `accounts` block) work unchanged.
### Config example
```json5
{
"channels": {
"matrix": {
"dm": { "policy": "open" },
"accounts": {
"default": { "name": "Main Bot" },
"coding": {
"homeserver": "https://matrix.example.org",
"userId": "@coding:matrix.example.org",
"accessToken": "syt_..."
}
}
}
},
"bindings": [
{ "agentId": "main", "match": { "channel": "matrix", "accountId": "default" } },
{ "agentId": "coding", "match": { "channel": "matrix", "accountId": "coding" } }
]
}
<!-- greptile_comment -->
<h2>Greptile Overview</h2>
<h3>Greptile Summary</h3>
This PR adds multi-account support to the Matrix extension by introducing `channels.matrix.accounts` for per-account overrides, threading `accountId` through monitor/handlers/routing so `bindings` can target specific Matrix accounts, and refactoring Matrix client + credential storage into per-account registries.
Key wiring changes include:
- `resolveMatrixAccount()` now merges base Matrix config with per-account overlays and restricts `MATRIX_*` env var fallbacks to the default account.
- Credentials for non-default accounts are stored under `credentials/matrix/accounts/{id}/`.
- The monitor builds an account-specific synthetic config (`cfg.channels.matrix = mergedAccount`) to reuse existing downstream helpers.
- Outbound/action client resolution now prefers the active client for the requested accountId.
The overall approach matches the stated Slack/Telegram pattern, but there are a few runtime-breaking regressions and multi-account enforcement gaps that should be addressed before merge.
<h3>Confidence Score: 2/5</h3>
- Not safe to merge as-is due to likely runtime API mismatches and behavior regressions in monitoring/routing.
- The multi-account refactor is substantial and mostly consistent, but the logger interface is currently inconsistent between monitor/index.ts, monitor/events.ts, and monitor/handler.ts in a way that can cause immediate runtime failures. There are also concrete behavior regressions around allowlist normalization and Matrix thread session handling that change security/routing semantics.
- extensions/matrix/src/matrix/monitor/index.ts, extensions/matrix/src/matrix/monitor/events.ts, extensions/matrix/src/matrix/monitor/handler.ts
<!-- greptile_other_comments_section -->
<sub>(2/5) Greptile learns from your feedback when you react with thumbs up/down!</sub>
<!-- /greptile_comment -->
Most Similar PRs
#11869: feat: Multi-account Matrix plugin with accountId routing
by jacoblyles · 2026-02-08
90.2%
#21105: feat(matrix): multi-account support
by omnibot1985 · 2026-02-19
89.2%
#23333: fix(matrix): add accountId routing for multi-account message sending 🤖
by BadTurki · 2026-02-22
82.3%
#14852: feat(matrix): add multi-account support
by tfm-neo-ai · 2026-02-12
82.0%
#6517: fix(matrix): pass accountId through outbound chain to resolveMatrix...
by saxyguy81 · 2026-02-01
81.2%
#13057: feat(matrix): add sessionScope=room to route sessions by roomId
by spengrah · 2026-02-10
75.2%
#6518: feat(matrix): add inbound message debouncing
by Klowalski · 2026-02-01
70.8%
#13832: feat(matrix): add sessionScope and thread-scoped inbound sessions
by yamoroc · 2026-02-11
70.1%
#20278: Fix/matrix missing bot sdk dependency
by saurav470 · 2026-02-18
69.7%
#8507: fix: preserve accountId for multi-account agent-to-agent messaging
by djh58 · 2026-02-04
69.6%