A developer built a working messenger in a single HTML file with no backend, no database, and no infrastructure. The twist? It actually works, and the accidental protocol it created might be the real story.
Sending a message to your mother should not require infrastructure comparable to a small bank. That's the observation behind Macaroni Messenger, a distributed messaging system implemented as a single HTML file. No backend. No database. No registration. Just Git.
The project, which was built overnight using AI coding tools, sounds like a joke. The author admits as much. But it works, and the protocol it accidentally created might be more interesting than the messenger itself.
The Architecture That Should Not Work
Macaroni Messenger stores every message as a JSON file in a Git repository. The frontend is HTML, CSS, and JavaScript. The backend does not exist. The database is Git. The transport layer is Git. The synchronization layer is Git.
When you send a message, the client creates a JSON file at a path like .macaroni/chats/<chat_id>/messages/YYYY/MM/DD/<message_id>.json and pushes it to GitHub. When you receive a message, the client pulls from the repository and reads the new files.
There is no WebSocket connection. No message broker. No real-time transport at all. New messages arrive through polling. Outgoing writes go through a local outbox. GitHub API rate limits are a real constraint, and the public demo is hardcoded to avoid burning unauthenticated rate limits on first load.
This is, by any conventional engineering measure, a terrible idea. "Unfortunately, it works," the author writes.
How to Actually Use It
The demo opens a hardcoded read-only .macaroni dataset, so the first screen does not require a GitHub token. You can read demo chats immediately by opening the HTML file in Chrome, Chromium, or Edge.
To write messages, you need a GitHub repository and a fine-grained token with Contents read/write access. The token, your name, and the repository URL go into Settings. That is the entire configuration.
The messenger can be distributed as a single file: via email, USB drive, Git repository, website, or a random forum attachment. If a browser can open it, it works. Deployment is copying the file somewhere.
The .macaroni Protocol
The interesting part is not the messenger. It is the directory structure inside the Git repository.
The .macaroni/ folder contains protocol metadata, user files, chat definitions, membership lists, messages organized by date, and an inbox system. This makes it a universal agent protocol over Git.
Not in the enterprise sense. In the practical sense: agents can read repository state, append structured JSON events, coordinate through commits, and rebuild local state from Git history. Humans can inspect and edit everything with normal Git tools.
The project describes this as accidental. The messenger was the first client. The protocol emerged from the file layout required to make the messenger work.
Privacy Is Not a Feature
Macaroni Messenger explicitly does not guarantee privacy. A public repository means public messages. A private repository means readable by everyone with repository access. Tokens are stored in browser localStorage, which is convenient but not secure.
The project suggests installing an encryption plugin if you need privacy, then adds: "Good luck." This is honest in a way most projects are not. The threat model is clear from the start.
What It Refuses to Build
The project maintains a list of things it will never support: Kubernetes, microservices, service mesh, message brokers, blockchain, enterprise AI features, and complexity for the sake of complexity.
The development philosophy is straightforward: before implementing anything, ask whether it can be solved with fewer files, without a backend, using Git, using JSON, using HTML, and in a way that is both functional and funny. Prefer that solution.
The entire client was built using AI coding tools. The author describes it as "1000% vibecoded," not because nobody knew what they were doing, but because modern tooling allows ideas to become software before common sense has a chance to stop them.
The Accidental Product
Macaroni Messenger is simultaneously a joke, a messenger, a Git client, a distributed append-only message log, a static web application, and a peer-to-peer communication protocol.
The FAQ asks: "Is this a joke?" Answer: "Partially." Does it actually work? "Unfortunately, yes."
The honest limitations are part of the appeal. There is no realtime transport. Large repositories will be slow. If a chat gets too large, create another repository. "This is called scaling," the documentation explains.
The project has documentation in both English and Russian, with files covering philosophy, product architecture, a roadmap, development steps, the protocol specification, and a guide for creating a portable HTML file for your mother with a preconfigured profile.
Why It Matters
The messaging space is dominated by platforms that require accounts, phone numbers, applications, updates, dependencies, regulations, and infrastructure. Macaroni Messenger starts with a different question: what is the minimum amount of technology required to send "Mom, please cook macaroni"?
The answer appears to be: HTML and Git.
The broader implication is that Git repositories can function as communication infrastructure. The .macaroni protocol turns a version control system into a message bus. Agents, bots, and humans can all read and write to the same structured data store using tools they already have.
This is not going to replace Signal or Telegram. It is not trying to. But as a demonstration of what becomes possible when you refuse to build infrastructure, it raises interesting questions about where the line between "real software" and "joke" actually sits.
If a message cannot be committed, was it worth sending?
Comments
Please log in or register to join the discussion