AGENTS.md — matrix-android

Progress log and architecture notes for AI agents working on this project.

Status

Component	Status
Build infrastructure (Gradle, version catalog)	done
Matrix networking (Retrofit API + Session)	done
SSO / password login flow	done
Room list screen	done
Chat screen (send + receive)	done
Terminal theme (green on black, monospace)	done
Launcher icon (vector adaptive)	done
README	done

Design decisions

No heavy Matrix SDK

Instead of importing the full matrix-android-sdk2 (used by Element), we call the Matrix REST API directly with Retrofit. This keeps the APK small and the code easy to follow. The trade-off is no E2E encryption support.

SSO via Custom Tabs

Login opens the homeserver's /login/sso/redirect endpoint in a Chrome Custom Tab. After auth the homeserver redirects to matrixandroid://sso?loginToken=<token>. The app intercepts this URI via an <intent-filter> in AndroidManifest.xml and exchanges the token for an access token.

MainActivity → AppNavigation hosts all three screens (Login, Rooms, Chat) inside a single NavHost. No fragments.

MatrixSession singleton

MatrixSession is a process-scoped singleton (companion object). It holds the Retrofit client, persists the access token in SharedPreferences, and runs the /sync long-polling loop in a coroutine scope. All screens observe syncState: StateFlow<SyncState>.

Sync filter

Initial and incremental syncs use a compact filter:

Timeline limited to 50 events per room
State events use lazy member loading
Presence and account data stripped

This prevents the first sync from being huge on accounts with many rooms.

Known issues / future work

E2E encryption: Matrix Olm/Megolm is not implemented. Encrypted rooms will show blank messages.
Push notifications: Not implemented. The app only receives messages while open.
Pagination: No scroll-back pagination for old messages.
Room member display names: Members are shown as their MXID, not display name.
Image/file messages: Silently dropped (only m.text is rendered).
Error handling: Network errors on send are silently swallowed; add a snackbar or retry UI.
Direct messages: DMs appear in the room list using the room ID; should resolve the other user's display name.

File map

matrix-android/
├── settings.gradle.kts
├── build.gradle.kts
├── gradle/
│   ├── libs.versions.toml          ← version catalog
│   └── wrapper/
│       └── gradle-wrapper.properties
├── app/
│   ├── build.gradle.kts
│   ├── proguard-rules.pro
│   └── src/main/
│       ├── AndroidManifest.xml
│       ├── java/com/ltadeu6/matrix/
│       │   ├── MainActivity.kt
│       │   ├── navigation/AppNavigation.kt
│       │   ├── auth/LoginScreen.kt
│       │   ├── auth/LoginViewModel.kt
│       │   ├── rooms/RoomListScreen.kt
│       │   ├── chat/ChatScreen.kt
│       │   ├── chat/ChatViewModel.kt
│       │   ├── matrix/MatrixApi.kt
│       │   ├── matrix/MatrixModels.kt
│       │   ├── matrix/MatrixSession.kt
│       │   └── ui/theme/Theme.kt
│       └── res/
│           ├── drawable/ic_launcher_foreground.xml
│           ├── mipmap-anydpi-v26/ic_launcher.xml
│           ├── mipmap-anydpi-v26/ic_launcher_round.xml
│           └── values/{strings,colors,themes}.xml
├── README.md
└── AGENTS.md

Session 1 — initial build (2026-05-14)

Inspected matrix-message terminal app for UI reference:
- app.py: curses chat with < prefix for incoming, > for outgoing
- font.py: big pixel ASCII font for incoming banners
- Color scheme: COLOR_GREEN on black
Created full Android project from scratch (no fork)
Chose Retrofit + kotlinx.serialization over matrix-android-sdk2 for simplicity
SSO flow: Custom Tabs → homeserver → matrixandroid://sso deep link → token exchange
Compose UI with monospace font, #00FF41 green, #0A0A0A background
All screens text-only, no images/icons/avatars

4.2 KiB Raw Blame History