#21105: feat(matrix): multi-account support
channel: matrix
size: M
Cluster:
Multi-Account Matrix Support
## Summary
This PR adds first-class multi-account support to the Matrix extension by introducing an `accounts` map in the Matrix config and threading `accountId` through client resolution, monitoring, and outbound/actions. It also adds an active-client registry keyed by account so outbound actions can reuse the correct running client, while keeping the shared client lifecycle safe across concurrent starts.
## Backward compatibility
Legacy single-account configuration remains supported: existing top-level Matrix fields (`homeserver`, `userId`, `accessToken`, etc.) still parse and continue to work without an `accounts` section. When no explicit `accountId` is provided, the default account key is used.
## Test coverage
- Unit tests added for Matrix config schema parsing (legacy + multi-account + invalid policy cases).
- Unit tests added for the per-account active-client registry behavior.
Note: local integration/e2ee tests that depend on the `matrix-sdk-crypto` native module cannot be exercised here because the native dependency is not installed in this environment; unit tests and build pass.
## Files changed
- `extensions/matrix/src/config-schema.ts`
- `extensions/matrix/src/matrix/client/shared.ts`
- `extensions/matrix/src/matrix/active-client.ts`
- `extensions/matrix/src/matrix/monitor/index.ts`
- `extensions/matrix/src/matrix/monitor/handler.ts`
New tests:
- `extensions/matrix/src/config-schema.test.ts`
- `extensions/matrix/src/matrix/active-client.test.ts`
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
Introduced multi-account support for Matrix by adding an `accounts` map to the config schema while preserving backward compatibility with legacy single-account configuration. The implementation threads `accountId` through client resolution, monitoring, actions, and outbound handlers. Storage paths are now account-scoped to prevent conflicts between multiple accounts on the same homeserver. An active-client registry keyed by account ID enables concurrent operation of multiple Matrix accounts while maintaining safe shared client lifecycle management.
<h3>Confidence Score: 5/5</h3>
- This PR is safe to merge with minimal risk
- The implementation follows clean patterns with comprehensive test coverage for config parsing and active-client registry. Backward compatibility is properly maintained through fallback logic, and the accountId threading is consistently applied across all components
- No files require special attention
<sub>Last reviewed commit: 9a98922</sub>
<!-- 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
89.8%
#13013: feat(matrix): multi account support
by ti · 2026-02-10
89.2%
#23333: fix(matrix): add accountId routing for multi-account message sending 🤖
by BadTurki · 2026-02-22
83.2%
#6517: fix(matrix): pass accountId through outbound chain to resolveMatrix...
by saxyguy81 · 2026-02-01
81.9%
#14852: feat(matrix): add multi-account support
by tfm-neo-ai · 2026-02-12
79.8%
#13832: feat(matrix): add sessionScope and thread-scoped inbound sessions
by yamoroc · 2026-02-11
72.9%
#13057: feat(matrix): add sessionScope=room to route sessions by roomId
by spengrah · 2026-02-10
72.3%
#16284: fix(feishu): route tool credentials by account parameter
by Yaxuan42 · 2026-02-14
70.3%
#20278: Fix/matrix missing bot sdk dependency
by saurav470 · 2026-02-18
69.4%
#13451: feat(matrix): add forceRoomRouting to bypass DM detection for allow...
by yamoroc · 2026-02-10
68.2%