software

Macaroni – a single HTML file messenger

Published: (June 11, 2026 at 02:32 AM EDT)
9 min read
Source: Hacker News

Source: Hacker News

Macaroni Messenger

1000% vibecoded One HTML File No Backend Git Powered Privacy License

A messenger implemented as a single HTML file

Russian version: README.ru.md.

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

Macaroni Messenger demo

Try It

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.

Run Locally

  • 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.

Send A Real Message

  • 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.

Demo Repository Structure

Macaroni files live under .macaroni/, so the messenger can be attached to any repository without turning the root into pasta.

.json chats//meta.json chats//members.json chats//messages/YYYY/MM/DD/.json inbox//.json”>

.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.

Honest Limitations

  • 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:

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.

Main Principle

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.

Why Does This Exist?

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

Architecture

Frontend:

  • HTML

  • CSS

  • JavaScript

Backend:

  • none

Database:

  • Git

Synchronization:

  • git fetch

  • git pull

  • git push

Search:

  • local index

Storage:

  • local browser storage

The Accidental Protocol

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 Entire Client Is A File

The client is:

messenger.html

Not an installer.

Not an archive.

Not a launcher.

Not a package.

Not a platform.

A file.

Double click.

The messenger starts.

Distribution

Macaroni Messenger can be distributed as:

messenger.html

via:

  • email

  • USB flash drive

  • Git repository

  • website

  • cloud storage

  • random forum attachment

If a browser can open it, it works.

Deployment

How do I deploy Macaroni Messenger?

Copy the file somewhere.

Deployment completed.

Privacy

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.

Identity

Every Macaroni Messenger client receives a small identifier.

Example:

SA6E

We do not guarantee uniqueness.

We tried.

If two users receive the same identifier:

we recommend introducing them to each other.

Storage Philosophy

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.

Message Format

Messages are files.

Files are messages.

A message is a JSON document.

Nothing more.

Nothing less.

Scaling

How does Macaroni Messenger scale?

Poorly.

If a repository becomes too large:

create a new repository.

Supported Infrastructure

Macaroni Messenger officially supports:

  • GitHub

  • GitLab

  • GitVerse

  • Forgejo

  • Gitea

  • a server in your basement

Basement Support

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

Enterprise Edition differs from Community Edition by having:

a second basement.

Development Process

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.

Vibe Coding

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.

AGENT RULES

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.

Things We Refuse To Build

  • Kubernetes support

  • Microservices

  • Service mesh

  • Message broker

  • Blockchain

  • Enterprise AI features

  • Complexity for the sake of complexity

FAQ

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.

What Is Macaroni Messenger?

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.

Final Statement

If a message cannot be committed,

was it worth sending?

0 views
#software #programming #tech-trends
View source
Share:
Back to Blog

Related posts

Read more »

Chaosnet (1981)

1 Introduction ¶Introduction Chaosnet is a local network, that is, a system for communication among a group of computers located within one or two kilometers o...

Rome Fell and Nobody Noticed

When I first began learning about the Roman Empire in middle school, I was most interested in what everyone else seems to be interested in — the time of Caesar...