Russian version: README.ru.md.

License: DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE.

The demo opens a hardcoded read-only .macaroni dataset, so the first screen does not burn unauthenticated GitHub API rate limit.

No token.

No registration.

No backend.

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.

1. Download messenger.html.
2. Open it in Chrome, Chromium, or Edge.
3. 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.

1. Create or choose a GitHub repository.
2. Create a fine-grained GitHub token with Contents: Read and write for that repository.
3. Open messenger.html.
4. Put your name, repository URL, and token into Settings.
5. 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/<client_id>.json
  chats/<chat_id>/meta.json
  chats/<chat_id>/members.json
  chats/<chat_id>/messages/YYYY/MM/DD/<message_id>.json
  inbox/<client_id>/<message_id>.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:

Russian documents:

Macaroni Messenger is a distributed messaging system implemented as a single HTML file.

Messages are stored in Git repositories.

The client is an HTML document.

The backend does not exist.

The database is Git.

The transport layer is Git.

The synchronization layer is Git.

The history storage is Git.

This sounds like a terrible idea.

Unfortunately, it works.

Do not make things complicated when they can be funny.

This does not prevent them from being real software.

Macaroni Messenger is not a joke.

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:

• registrations
• phone numbers
• centralized services
• applications
• updates
• dependencies
• regulations
• 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:

Frontend:

Backend:

Database:

Synchronization:

• git fetch
• git pull
• git push

Search:

Storage:

One side effect of Macaroni Messenger is the .macaroni protocol.

At first, .macaroni is just a boring directory inside a Git repository.

It contains:

• protocol metadata
• users
• chats
• members
• messages
• inbox hints

But this also makes it a universal agent protocol over Git.

Not in the enterprise sense.

In the practical sense:

• agents can read repository state;
• agents can append structured JSON events;
• agents can coordinate through commits;
• agents can rebuild local state from Git history;
• humans can inspect and edit everything with normal Git tools.

Macaroni Messenger is the first client.

The .macaroni directory is the part that accidentally looks reusable.

Unfortunately, that also works.

The client is:

Not an installer.

Not an archive.

Not a launcher.

Not a package.

Not a platform.

A file.

Double click.

The messenger starts.

Macaroni Messenger can be distributed as:

via:

• email
• USB flash drive
• Git repository
• website
• cloud storage
• random forum attachment

If a browser can open it, it works.

How do I deploy Macaroni Messenger?

Copy the file somewhere.

Deployment completed.

Macaroni Messenger does not guarantee privacy.

In fact, it explicitly guarantees the opposite.

If your repository is public:

your messages are public.

If your repository is private:

everyone with repository access can read them.

If you need privacy:

install an encryption plugin.

Good luck.

Every Macaroni Messenger client receives a small identifier.

Example:

We do not guarantee uniqueness.

We tried.

If two users receive the same identifier:

we recommend introducing them to each other.

Git is the source of truth.

Everything else is a cache.

If local storage disappears:

rebuild it.

If the index disappears:

rebuild it.

If the browser profile disappears:

rebuild it.

Git remains.

Messages are files.

Files are messages.

A message is a JSON document.

Nothing more.

Nothing less.

How does Macaroni Messenger scale?

Poorly.

If a repository becomes too large:

create a new repository.

Macaroni Messenger officially supports:

• GitHub
• GitLab
• GitVerse
• Forgejo
• Gitea
• a server in your basement

Macaroni Messenger officially supports basement deployments.

If your server:

• stands on a chair
• uses an extension cord
• makes suspicious noises
• is located near jars of pickles

it is considered a supported configuration.

Enterprise Edition differs from Community Edition by having:

a second basement.

Macaroni Messenger was built overnight.

The author wrote a roadmap.

The author went to sleep.

The coding agent continued implementing the roadmap.

The author woke up.

The messenger existed.

This repository is the result of that mistake.

Macaroni Messenger is proudly:

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.

Before implementing anything, ask:

Can this be solved with fewer files?

Can this be solved without a backend?

Can this be solved using Git?

Can this be solved using JSON?

Can this be solved using HTML?

Can this be solved in a way that is both functional and funny?

Prefer that solution.

• Kubernetes support
• Microservices
• Service mesh
• Message broker
• Blockchain
• Enterprise AI features
• Complexity for the sake of complexity

Is this a joke?

Partially.

Does it actually work?

Unfortunately, yes.

Why Git?

Because Git already knows how to store files.

Why HTML?

Because it is funny.

Why not Telegram?

Telegram already exists.

Why not Matrix?

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 Messenger is simultaneously:

• a joke
• a messenger
• a Git client
• a distributed append-only message log
• a static web application
• a peer-to-peer communication protocol

and, accidentally,

a real product.

If a message cannot be committed,

was it worth sending?