Macaroni – a single HTML file messenger

Russian version: README.ru.md.

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.

No token.

No registration.

No backend.

You can read demo .macaroni chats immediately. To read or write a real repository today, open Settings and connect a GitHub repository. GitHub is the first built-in browser adapter, not a protocol requirement.

The .macaroni/ protocol can live in any git repository. A non-GitHub host needs a browser-compatible provider adapter: host API, CORS-enabled HTTPS file API, WebDAV-style git bridge, or a wrapper that exposes native git operations to the same HTML client.

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.
• The .macaroni/ protocol is git-host agnostic. Any repository can store it.
• GitHub is the only built-in write adapter right now.
• GitLab, GitVerse, Gitea, Forgejo, self-hosted git, and other hosts need browser-compatible adapters. Today they are protocol targets, not finished built-in write adapters.
• Plain browser tabs cannot do raw SSH git. That needs a wrapper or host API, because browsers are funny in the wrong direction.
• 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:

• PHILOSOPHY.en.md - the main project principle.
• docs/product-brief.en.md - detailed product and architecture brief.
• docs/roadmap.en.md - current implementation roadmap.
• docs/development-steps.en.md - sequential development plan.
• docs/protocol-v1.en.md - Macaroni Protocol v1 file model.
• docs/github-provider.en.md - first real provider adapter.
• docs/generic-git-provider.en.md - how non-GitHub git hosts fit the transport contract.
• docs/plugin-boundary.en.md - browser-side plugin boundary.
• docs/electron-wrapper.en.md - optional Electron/WebView wrapper contract.
• docs/settings-export-import.en.md - manual settings backup and restore.
• docs/portable-mom.en.md - portable HTML file for mom with a preconfigured profile.
• CONTRIBUTING.md - contribution rules: one HTML file, no backend cosplay.
• docs/show-hn.md - Show HN pitch and FAQ.
• docs/browser-support.en.md - supported browser feature matrix.
• docs/access-token.en.md - how to get an access token.
• docs/gitverse-token.en.md - how to get a GitVerse access token.

Russian documents:

• README.ru.md
• PHILOSOPHY.md
• docs/product-brief.md
• docs/roadmap.md
• docs/development-steps.md
• docs/protocol-v1.md
• docs/github-provider.md
• docs/generic-git-provider.md
• docs/plugin-boundary.md
• docs/electron-wrapper.md
• docs/settings-export-import.md
• docs/portable-mom.md
• docs/show-hn.ru.md
• docs/browser-support.md
• docs/access-token.md
• docs/gitverse-token.md

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:

• HTML
• Git
• JSON

Frontend:

• HTML
• CSS
• JavaScript

Backend:

• none

Database:

• Git

Synchronization:

• git fetch
• git pull
• git push

Search:

• local index

Storage:

• local browser 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?