Macaroni – a single HTML file messenger

License: DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE. Live demo: open Macaroni Messenger. Download: messenger.html. Source repo: github.com/vanyapr/makaroshki. The demo opens a hardcoded read-only .macaroni dataset, so the first screen does not burn unauthenticated GitHub API rate limit. You can read demo .macaroni chats immediately. To read or write a real repository, open Settings and connect a GitHub repository. To write messages, you need a GitHub token with repository Contents read/write access, because GitHub is the backend we refused to build. Download messenger.html. Open it in Chrome, Chromium, or Edge. Use the default public repository in read-only mode, or open Settings and connect your own repository. localhost is not part of the product. Double click is. Create or choose a GitHub repository. Create a fine-grained GitHub token with Contents: Read and write for that repository. Open messenger.html. Put your name, repository URL, and token into Settings. Write something worth committing. Detailed guide: How to get an access token. Macaroni files live under .macaroni/, so the messenger can be attached to any repository without turning the root into pasta. .macaroni/ protocol.json users/ .json chats/ /meta.json chats/ /members.json chats/ /messages/YYYY/MM/DD/ .json inbox/ / .json The demo data is hardcoded inside messenger.html; a real connected repository uses the same layout. Macaroni Messenger is not private. Public repository means public messages. Private repository means readable by everyone with repository access. GitHub is the only working write provider right now. GitLab, GitVerse, Gitea, Forgejo, and other git hosts are protocol targets for future adapters. Today they are not finished write adapters. Browser support is intentionally strict: persistent storage for file:// or https://, localStorage, IndexedDB, and WebCrypto are required. Recommended browsers: Chrome, Chromium, Edge. There is no realtime transport. New messages arrive through polling, and outgoing writes go through a local outbox. GitHub API rate limits exist. The public demo is hardcoded to avoid burning unauthenticated rate limit on first load. Real connected repositories still use GitHub API. Tokens are stored in browser localStorage. This is convenient, not secure storage. Never paste a real token into public chat, screenshots, issues, README examples, or Hacker News comments. If you did, revoke it. Large repositories will be slow. If a chat gets too large, create another repository. This is called scaling. Documents: Macaroni Messenger is a distributed messaging system implemented as a single HTML file. Messages are stored in Git repositories. Do not make things complicated when they can be funny. This does not prevent them from being real software. It simply refuses to introduce complexity without a reason. Macaroni Messenger was born from a simple observation. Sending a message to your mother should not require infrastructure comparable to a small bank. Modern communication systems are increasingly built around: Macaroni Messenger starts with a different question: What is the minimum amount of technology required to send: One side effect of Macaroni Messenger is the .macaroni protocol. At first, .macaroni is just a boring directory inside a Git repository. But this also makes it a universal agent protocol over Git. The .macaroni directory is the part that accidentally looks reusable. Macaroni Messenger can be distributed as: Macaroni Messenger does not guarantee privacy. In fact, it explicitly guarantees the opposite. everyone with repository access can read them. Every Macaroni Messenger client receives a small identifier. If two users receive the same identifier: we recommend introducing them to each other. Macaroni Messenger officially supports basement deployments. it is considered a supported configuration. Enterprise Edition differs from Community Edition by having: The coding agent continued implementing the roadmap. This repository is the result of that mistake. 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. Can this be solved in a way that is both functional and funny? Kubernetes support Microservices Service mesh Message broker Blockchain Enterprise AI features Complexity for the sake of complexity FAQ Is this a joke? Because Git already knows how to store files. We just wanted to tell our mom to cook macaroni. Why is there more documentation than source code? Because explaining the project is harder than implementing it.

Macaroni – a single HTML file messenger

Key takeaways

More in computer-science