Macaroni — a single HTML file messenger
Macaroni Messenger is an open-source distributed messaging system implemented as a single HTML file that uses Git repositories as its backend. With no server, database, or registration required, the project challenges modern messaging infrastructure complexity by proving that HTML, Git, and JSON are sufficient for functional distributed communication. The GitHub project has attracted a growing community of developers interested in radically minimalist software design.
Macaroni Messenger: A Distributed Chat System in a Single HTML File
What if sending your mom a message didn't require a cloud infrastructure comparable to a small bank? That's exactly the question developer vanyapr set out to answer with Macaroni Messenger, an open-source distributed messaging system implemented as a single HTML file. No server, no database, no registration, no app store — just HTML, Git, and JSON.
Macaroni Messenger has been gaining traction on GitHub with an active community of contributors drawn to its radically minimalist approach. The project challenges one of the most deeply entrenched assumptions in modern software: that communication apps require complex backend infrastructure to function.
The Architecture: Backend-Free Design
Macaroni Messenger's architecture is refreshingly sparse:
- Frontend: HTML, CSS, and JavaScript — all contained in a single downloadable file
- Backend: None — the concept of a server is entirely absent
- Database: Git repositories store messages as structured JSON files
- Synchronization: Standard Git operations — fetch, pull, and push
- Storage: Browser localStorage and IndexedDB for client-side state
- Search: Built into the browser's local index
Messages are stored in a .macaroni/ directory within any Git repository, organized by chat ID and date. The protocol is completely git-host agnostic — it works with GitHub, GitLab, Gitea, Forgejo, or any self-hosted Git server that exposes a browser-compatible API.
How It Works
Getting started with Macaroni Messenger takes seconds, not hours:
- Download the
messenger.htmlfile from the project's GitHub repository - Open it in Chrome, Chromium, or Edge — no installation, no npm install, no server configuration
- Connect a GitHub repository via the Settings panel using a fine-grained access token with Contents: Read and Write permissions
- Start messaging — every message is committed as a JSON file to your repository
The .macaroni/ directory structure organizes everything with a clean, intuitive layout:
protocol.json— protocol version and metadatausers/<client_id>.json— per-client user profileschats/<chat_id>/— chat metadata, members, and messages organized by dateinbox/<client_id>/— incoming message queue
New messages arrive through periodic Git polling, and outgoing writes pass through a local outbox. There is no real-time transport — the simplicity trade-off means messages arrive when the client polls, not instantly via WebSocket. For many use cases, this is more than sufficient.
The Philosophy: Radical Simplicity
The project's philosophy document is refreshingly direct. Macaroni Messenger "simply refuses to introduce complexity without a reason." It is not a joke or a proof of concept — it is a fully functional piece of software that deliberately strips away the layers of infrastructure that modern communication systems have come to accept as necessary.
The project notes that modern messaging systems are "increasingly built around registrations, phone numbers, centralized services, applications, updates, dependencies, regulations, and infrastructure." Macaroni Messenger asks what the minimum viable technology stack is, and the answer is HTML, Git, and JSON.
Under its DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE, the project invites anyone to use, modify, and distribute the code freely.
Honest About Limitations
One of the most refreshing aspects of Macaroni Messenger is its transparency about what it does not do well:
- No privacy by default: Public repositories mean public messages. Private repositories limit access to collaborators but anyone with repo access can read messages.
- No real-time transport: Messages are delivered through polling, not push notifications. This is a trade-off for the zero-infrastructure approach.
- Strict browser support: Chrome, Chromium, or Edge are required for persistent storage APIs like IndexedDB and WebCrypto.
- Token security: GitHub access tokens are stored in browser localStorage — convenient for development, but not a production-grade security solution.
- API rate limits: GitHub API rate limits apply to connected repositories, though the public demo avoids burning unauthenticated rate limits with hardcoded data.
- No scaling for large chats: Large repositories become slow. The recommended solution is admirably straightforward: create a new repository when a chat gets too large.
Who Should Use Macaroni Messenger?
Macaroni Messenger is not competing with WhatsApp, Telegram, or Signal. It serves a different audience entirely:
- Small development teams who want a zero-infrastructure internal chat tool that requires no deployment
- Developers and tinkerers who want to understand how a Git-backed messaging protocol works under the hood
- Privacy-conscious users who want full control over their message storage without trusting a third-party provider
- Anyone who finds the proposition of "download an HTML file, open it, and start chatting" genuinely compelling
For the right audience, Macaroni Messenger is not just a curiosity — it is a genuinely useful tool. A live demo is available that opens a hardcoded read-only dataset, allowing anyone to explore the interface without connecting a repository or risking API rate limits.
The Bigger Picture
Macaroni Messenger belongs to a broader movement toward simpler, more distributed software. As cloud infrastructure costs continue to rise and centralized platforms face growing scrutiny over privacy and data control, projects like this offer a glimpse of an alternative future — one where users own their data, the infrastructure is a Git repository, and the application is a file you can double-click.
The .macaroni protocol itself may prove to be the project's most lasting contribution. A standardized way to store and synchronize structured data in Git repositories has applications far beyond messaging — collaborative document editing, lightweight task management, and decentralized CRM systems could all benefit from the same pattern.
For now, Macaroni Messenger is a working, usable, and delightfully minimal communication tool that proves a powerful point: sometimes the best software is the simplest. Download the HTML file, connect a repository, and send someone a message. It just works.


