Project Nayuki

MamIRC, the headless IRC client

MamIRC screenshot



MamIRC is designed for users who want portable web access, high connection uptime, and accurate logging.

The software comes in three parts. The backend consists of two Java programs, which you run continuously on a server computer. The frontend user interface is a web page, which can be accessed from a web browser of your choice – on any computer, smartphone, or tablet.

Nayuki already uses MamIRC full-time as the primary IRC client for personal communications, running continuously since Oct 2015. Although the software is not feature-complete (considered to be alpha or beta stage), it implements enough basic chat functionality and is stable enough to be worth running.

The source code is in the development repository on GitHub . Setup instructions are linked below, but it is recommended to skim the whole overview before deciding whether MamIRC is suitable for you. The software is named after Tomoe Mami (巴 マミ) for her headless incident, and is pronounced [ˈma.miʔ.aɪ.aɹ.si].

Frontend software: HTML+CSS+JS+images

The frontend is a web-based user interface, usable in most desktop and mobile modern web browsers on popular operating systems. The user interface can be accessed without installing extra software on the user’s computing device. It has been tested to work properly in Mozilla Firefox, Google Chrome, Apple Safari, Opera; probably working in Microsoft Edge, and probably various degrees of brokenness on different versions of Microsoft Internet Explorer.

For users, this web UI is the centerpiece of the MamIRC software package. The interface is simple and easy to learn, but doesn’t support all the features of a traditional IRC client. The interface is designed somewhat differently from other clients – it is optimized for high information content and low wasted space. As a result, text is one line per message (instead of putting the name or timestamp on a separate line), there is only one sidebar (instead of two), and there are no horizontal bars that span the entire width (because vertical space is precious). There is an alternate version of the web UI that works better for mobile devices with limited screen space.

The default user interface is themed on Tomoe Mami, and features some moe (萌え) design elements. If this look is not to your liking, the CSS code can be modified with basic skills in web design and a bit of patience.

Backend software: Java + SQLite

The backend can run on any Linux or Windows machine (OS X and BSD untested) that has a Java Development Kit installed, version 7 or above. (The software is distributed as source code, so a JDK is required for compilation. However it is feasible to compile on another machine and put the MamIRC JAR on the server, so that the server only needs to have a JRE.) In addition to Java, the backend also needs to run an SQLite native library. The backend Java programs run on the command line and need no GUI (e.g. X Window System), hence why this IRC client is considered “headless”.

The machine needs some disk space to store the MamIRC software (~10 MB read-only), user configuration (~1 KB read/write), and chat log (growing about 1 MB per day, give or take an order of magnitude depending on IRC chattiness). It is strongly recommend that the machine be restarted very infrequently (due to power outages, software/OS updates, or hardware/software failures), because launching MamIRC manually isn’t particularly fun. Also it’s good to have a stable Internet connection (data center preferred, home ISP dubious), because generally speaking it’s a bad experience to be momentarily disconnected from IRC.

Design philosophy

All of the code is written from scratch by Nayuki, especially the interpretation of the IRC protocol and the user interface. Because it is not based on existing software, it shares no architecture/design, implementation bugs, or legacy constraints with any other IRC client. (MamIRC has its own idiosyncratic issues however.)

Most features of MamIRC are standard among IRC clients and aren’t worth highlighting, however two uncommon features deserve a mention:

  • Can be hot-upgraded without dropping the user’s connections to IRC servers or losing messages.
  • Saves a raw protocol-level log that is more detailed than any other IRC client’s chat log.

These two features combined make MamIRC the ideal choice for a developer: The hot-upgradability means that the user doesn’t miss any messages on their active IRC networks and that other IRC users see no indication of the user upgrading/modifying/restarting the software. The low-level IRC log makes it possible to detect unhandled or mishandled commands, allows the developer to implement or fix the behavior, and lets the new software re-parse the log to interpret the IRC protocol more correctly.

Note that MamIRC is not a multi-user or team IRC client, unlike some recently released web-based IRC software from competitors. The implementation of the single-user MamIRC is complex enough for my taste, and making it multiuser-capable requires numerous design choices regarding sharing, administration, and security. Also it is harder to prevent denial-of-service or CPU/memory-exhaustion attacks when a single process is responsible for serving multiple users. (Of course it is possible to run one copy of MamIRC per user, but this comes at a per-user cost of two processes and ~200 MB of RAM.)


Written documentation is included in the project repository. Here are quick links to view the doc pages:


Currently implemented features in MamIRC:

Chatting / IRC protocol
  • Chatting, joining, parting channels
  • Sending/receiving private/direct messages
  • Full Unicode text support (UTF-8 encoding, including emoji)
  • Basic IRC commands like /nick, /whois, etc.
  • Showing and setting the channel topic
  • Receiving/sending NOTICEs
Data display
  • Nickname colorization
  • Clikable URL links
  • Showing formatted and colored text
  • Date headings for easy skimming
  • New messages count
  • Toast notification upon nickflag
Text input
  • Multi-line input text box
  • Tab completion for nicknames
  • Special input indicators
User interaction
  • Desktop- and mobile-optimized interfaces
  • Mark messages as read
  • Clear message lines
  • Mute window
  • Form to configure IRC servers and channels
  • Detection of dropped connections, automatic reconnect to server
  • Auto-join list of channels, NickServ password on connect
  • Stable Connector software
  • Hot-upgradable Processor and web UI
  • Corruption-resistant logs due to SQLite

Planned features – these have a demonstrated need, and will be implemented in the near-term as time permits:

  • User privilege indicators (operator, voice, etc.)
  • Advanced muting options
  • Tools for working with the SQLite database
  • Per-channel and per-user plain text chat log files
  • Character encodings other than UTF-8
  • Statistics and visualization tools

Unsupported features – these are rarely used, high complexity, or otherwise not worth the cost:

  • Client-to-client protocol (CTCP), Direct Client-to-Client (DCC), file transfers (send/receive)
  • User-scriptable behavior and actions, plug-ins, etc.
  • Support for older versions of Microsoft Internet Explorer


() Thank you for your interest in the MamIRC project. As mentioned in the introduction section, this software is already stable, and has enough features implemented that you can run it as a serious IRC client today. Currently, Nayuki and a couple of early adopters are running MamIRC full-time (“dogfooding”) as their primary IRC client.

However, the software is not ready yet for a publicly announced release. Some features are not designed well – the initial setup procedure of the backend needs to be streamlined, and there is no convenient way to retrieve chat logs (unless you like writing SQL statements?). Also, when the software is ready for release, a public IRC channel will be created to welcome discussion and feedback about the software and the project. Until the time comes, please watch this page and the commit log, and stay tuned for further updates!


Nayuki would like to thank the following people for helping the MamIRC project:

Contributors (patches, code review, or graphic design)

Luqman, Stephen Clement, Tai, Tyler Freedman.

Testers (with constructive feedback)

Alex Freedman, Kaens, Tai, Tyler Freedman.

Project links

MamIRC: Copyright © Project Nayuki. All rights reserved. No warranty.