shinkuan/Akagi

What is Akagi?

Akagi is a desktop assistant that watches you play online mahjong (Mahjong Soul, Tenhou, Riichi City, etc.) and gives you real‑time analysis. While you play, it shows a small overlay (HUD) with useful numbers such as:

• Shanten – how many tiles you are away from a ready hand
• Waits – which tiles will complete the hand
• Agari / Tenpai rates – the probability of winning or being in tenpai
• Deal‑in risk per opponent – how dangerous each opponent’s discards are
• Suggested discard – the tile the built‑in AI thinks is best to throw away

The overlay can be moved and resized, and the app also records every finished match so you can later view statistics, rank distribution, point‑trend charts, and detailed per‑hand data.

---

How does it work?

1. Capture the game data – Akagi can either:
   • Run a MITM proxy that intercepts the game’s WebSocket traffic (you install a tiny self‑signed CA once), or
   • Launch a Chromium‑based browser and sniff the WebSocket frames via the Chrome DevTools Protocol, which needs no certificate.
2. Convert the raw frames into a standard mjai event stream (a common JSON format for Japanese riichi‑mahjong). This is done by a platform‑specific bridge (Mahjong Soul, Tenhou, …).
3. Feed the events to a bot – two back‑ends are available:
   • Built‑in bot – a small neural network compiled into the Rust binary (using HuggingFace’s candle library). It runs locally, needs no download, and works for both 4‑player and 3‑player (sanma) games.
   • Cloud inference – an optional remote model that can be stronger. The local model stays loaded as a fallback, so a slow or unavailable server never stalls the game.
4. Display the analysis – the HUD shows the numbers above, and the History tab visualises accumulated stats.
5. Optional AutoPlay – when enabled, the bot can actually make moves for you (clicking tiles in the Chromium window or sending actions directly to Tenhou).

All components communicate through a lightweight event‑bus inside a single Rust binary, while the UI is built with Tauri 2, React 19 and Tailwind CSS.

---

Who might find it useful?

• Casual players who want instant feedback on their decisions and want to learn what a “good” discard looks like.
• Students of mahjong theory who need quick access to shanten, wait lists, and risk metrics while they play.
• Developers / researchers interested in a ready‑made example of real‑time game‑state capture, a Rust‑based neural‑net inference pipeline, and a bridge between a web game and a desktop UI.

---

How to get started

1. Download a release – a zip file for Windows, macOS (Apple Silicon) or Linux is provided on the Releases page. Unzip anywhere and run the akagi executable.
2. Run the Setup wizard – it asks for language, the platform you’ll play on, the capture mode (MITM or Chromium), and whether you want the cloud‑inference key.
3. Play a game – either launch the built‑in Chromium browser from Akagi or configure your existing client to use the local proxy (127.0.0.1:23410). The HUD will appear automatically.
4. Explore the History tab after a few matches to see win‑rate charts, PT trends, and per‑hand statistics.

---

Limitations & caveats

• The built‑in neural net is deliberately modest; it gives sensible advice but is not a top‑tier engine.
• Using the MITM proxy requires installing a self‑signed CA and, on Windows, a third‑party redirector like Proxifier. Forgetting to exclude loopback traffic can cause the game to misbehave.
• Cloud inference needs a purchased or redeemed key; without it the app falls back to the local model.
• Only complete games are saved; if you disconnect mid‑hand the partial data is discarded.
• The software is for educational purposes only; using it may violate the terms of service of the games, and any account penalties are the user’s responsibility.

---

Quick reference

Feature	Detail
Supported games	Mahjong Soul, Tenhou, Riichi City (future: Amatsuki)
Capture modes	MITM proxy (system‑wide) or Chromium CDP (no CA)
Bots	Built‑in Rust NN, optional cloud‑hosted model, external mjai plugins
Platforms	Windows x64, macOS ARM64, Linux x64 (glibc 2.35+)
UI tech	Tauri 2 + React 19 + TypeScript + Tailwind
License	Apache 2.0

---

Akagi is essentially a real‑time AI‑assisted analytics tool for online riichi mahjong, packaged as a single portable binary with optional cloud‑based inference.