Akagi

「死ねば助かるのに………」 - 赤木しげる

Real-time mahjong AI assistant for Mahjong Soul, Tenhou, and more.

Akagi V3: A single-binary Rust + Tauri rewrite of Akagi and AkagiNG.

Ask anything on Discord · Report Bug · Request Feature · DeepWiki

Other branches:

English · 繁體中文 · 简体中文

About

The purpose of this project is to provide a convenient way to understand your performance in mahjong matches in real time and to learn from it. This project is intended for educational purposes only. The author is not responsible for any actions taken by users. Game developers and publishers reserve the right to act against users who violate their terms of service; any consequences (account suspension, etc.) are the user's responsibility.

Akagi watches your Mahjong Soul / Tenhou game over a local proxy or a built-in browser, mirrors the game state, and shows shanten, waits, agari rate, tenpai rate, per-opponent deal-in risk, and a recommended discard in a draggable HUD. A built-in AI model ships inside the app — nothing to install — and its suggestion appears each turn; point it at the cloud inference API when you want a stronger, hosted model.

Screenshots

https://github.com/user-attachments/assets/42812e85-ccf0-49fd-b825-adbb5b7b58b0

https://github.com/user-attachments/assets/2ce7cb71-8b25-4895-a12b-0a638665dcab

https://github.com/user-attachments/assets/d5bc6ff6-6560-4365-ae55-660c9a522790

Table of Contents

For users

• Features
• Supported Platforms
• Quick Start
• Bots
• Game History
• Logs & Diagnostics
• Troubleshooting
• Roadmap

For developers

• Architecture
• Tech Stack
• Project Layout
• mjai Bots (plugin interface)
• Build From Source
• Testing
• Releases & CI
• Reference Materials
• License & Attribution
• Acknowledgements

Features

• Live HUD — shanten, waits, agari rate, tenpai rate, per-opponent deal-in risk, suggested attack/defence discard. Draggable, resizable UI layout.

• Two capture modes

  • MITM proxy (default) — system-wide; needs a one-time CA trust.
  • Chromium — Akagi launches a controlled Chromium-family browser and intercepts WebSocket frames via the Chrome DevTools Protocol. Zero proxy/CA setup; just play in the launched window.

• Two bot backends

  • Built-in bot (default) — a pure-Rust neural net embedded in the binary. No Python, no download, no setup; it just plays, in both 4-player and 3-player.
  • Cloud inference (optional) — hand each decision to a hosted, stronger model. The built-in model stays loaded as an automatic fallback, so an unreachable server never stalls a live game. Keys are bought or redeemed from inside the app.

  Per-mode routing throughout: bot.active_4p and bot.active_3p swap automatically based on the table's player count.

• Game history — every completed match is auto-recorded. The History tab shows a rank pie chart, a cumulative PT line chart with selectable scoring rules (Mahjong Soul tiers / Tenhou ranks / Custom uma), and detailed stats (win rate, deal-in rate, riichi rate, fuuro rate, ryukyoku rate, average winning / deal-in points, average winning turn, yakuman / nagashi-mangan counts).

• Simple first-run setup — language → platform → capture mode → CA trust / Chromium pick → bot settings → done.

• Internationalization — English, 日本語, 繁體中文, 简体中文. Live switch from Setup or Settings.

• Sanma (3-player) — fully supported: AI analysis, per-mode bot routing, history stats, 3p uma tables.

• In-app updates — checks for new releases on launch and on demand from Settings → Updates; one click downloads the update, applies it in place, and restarts. Read-only installs (e.g. AppImage) fall back to the release page.

Supported Platforms

Quick Start

A. Install a release

Akagi ships as a portable zip — one self-contained folder per platform. Download the file for your OS from Releases, unzip anywhere you have write permission (e.g. ~/Apps/, Desktop), and run akagi inside. Configuration, logs, history, the CA cert, and bots are all created right next to it, so moving / backing up / uninstalling is just moving / copying / deleting the folder.

On first launch the Setup wizard walks you through language, platform, capture mode, bot settings, and CA trust (only if you choose MITM mode). There is no bot to install — the built-in one is already there.

B. Chromium mode (no CA trust needed)

The simplest path. After Setup, Akagi finds Chrome / Edge / Brave / Chromium automatically and launches it with its own separate profile; log in to Mahjong Soul and play.

Frames are intercepted via the Chrome DevTools Protocol — no system proxy, no certificate.

C. MITM mode

System-wide proxy with a self-signed root CA at ./ca/:

1. Trust the certificate ./ca/akagi-ca.crt (or .cer / .pem / .der).
2. Route the game client through 127.0.0.1:23410. Health probe: GET /ping → pong.
3. On Windows, Proxifier is the usual way to redirect a specific application to the proxy.
4. Exclude loopback from that redirection. Send localhost, 127.0.0.1 and ::1 direct, never through Akagi.

[!IMPORTANT] Step 4 is not optional. Games talk to themselves over loopback for internal bookkeeping, and a redirector rule that matches the game for any target host will sweep those sockets into Akagi too. Akagi refuses them (you will see a refusing CONNECT to loopback warning in the log), but the game may still misbehave — so exclude loopback at the source.

In Proxifier: Profile → Proxification Rules, enable the built-in Localhost rule (Action: Direct) and drag it above your game rule. Order matters — Proxifier takes the first rule that matches, so a Localhost rule sitting below the game rule never fires.

Bots

Built-in bot (no install)

Akagi ships a built-in, pure-Rust bot. It's the default for both modes (bot.active_4p = "akagi-native", bot.active_3p = "akagi-native3p") and appears at the top of the Bots tab, always "ready".

It's a small neural net trained by behavior cloning (weights are embedded in the binary), so its strength is modest by design — a sensible default, not a top-tier engine.

Cloud inference (built-in bot)

The built-in bot can optionally hand its decisions to a remote inference server instead of running its embedded model — a stronger, hosted model reached over the network. The embedded local model stays loaded as an automatic fallback: if the server is unreachable, rate-limited, or the key is invalid, the bot plays the local model's move so a live game never stalls.

Getting a cloud-inference key

Three ways:

• Buy key — an in-app purchase.
• Redeem code — turn a prepaid code into a key, or add time to the key you already hold.
• Ask in the Discord server.

Request timeout

Each move is fetched from the server with a request timeout (default 3000 ms, adjustable in the cloud-inference settings, bounded to 500–10000 ms). If a response doesn't arrive in time, that turn falls back to the offline local model. Raise it to tolerate a slower server or connection; lower it to give up sooner. Note that a riichi costs two requests (declare, then discard) within one turn, so very high values risk overrunning the game's turn timer.

Per-mode bots

bot.active_4p and bot.active_3p are independent. Akagi picks the right one when the game starts, based on the table's player count.

Beyond these two backends, Akagi can also run external mjai bots as subprocesses. That's an extension point for developers rather than a step anyone needs — see mjai Bots (plugin interface).

Game History

Every cleanly-ended match (one that produced an end_game mjai event) is persisted under /history/:

/history/
├── index.jsonl              # one GameRecord per line (ULID-keyed)
└── games/
    └── .mjai.jsonl    # full event-stream copy

Mid-game disconnects leave an unfinalised buffer and are silently dropped — only complete games make it to disk.

The frontend's History tab shows:

• Rank pie chart — 1st / 2nd / 3rd / 4th distribution (3 slices for sanma).
• Cumulative PT line chart — selectable scoring rule:
  • Mahjong Soul: pick 場次 (銅 / 銀 / 金 / 玉 / 王座) and 段位 (初心 1 星 → 魂天).
  • Tenhou: pick 段位 (新人 → 天鳳位 across 21 ranks).
  • Custom: edit the uma + dan-bonus arrays directly. Switching rule / dan re-renders immediately — no backend round-trip.
• Detailed stats — win rate, deal-in rate, riichi rate, fuuro rate, ryukyoku rate, average winning / deal-in points, average winning turn, yakuman / nagashi-mangan counts.
• Game list — filterable by platform / players / east-or-south / date. Click a row for final standings + per-game stats; the trash icon deletes both the index entry and the per-game .mjai.jsonl.

PT-rule and filter selections persist to localStorage. Records load from the backend on bridge boot and stay current via the history-recorded Tauri event.

See src/history/README.md for the math, the storage schema, and how to add a new platform / stat field / filter dimension.

Logs & Diagnostics

Per-session logs land under //:

//
├── all.log                       # combined tracing output
├── .log                  # per-module filtered logs
├── proxy.binlog                  # raw binary WS frames
├── majsoul/.log         # per-WebSocket flow JSON log
├── majsoul/.mjai.jsonl  # per-game mjai event stream
└── inspector.jsonl               # frames seen by the Inspector

The frontend's Logs route has two tabs:

Diagnostic

Filterable application log. Filter by level (trace / debug / info / warn / error) and by module. Live-tail or browse past sessions; click a row to see source location + raw structured fields. An Open Folder button reveals the session directory in the OS file manager.

Inspector

Protocol-level frame viewer. Three entry types:

• WS Frame — raw binary (base64-truncated) plus the bridge's first-pass parse.
• MjaiEvent — decoded events flowing to the bot.
• BotReaction — bot responses with the meta field (confidence / q-values / whatever the bot emits).

Frame counts show how many mjai events each WS frame produced. Useful when debugging a bot or a bridge issue.

Troubleshooting

[!TIP] Reproduce the problem, then save the session folder under // — it has everything (app log, raw frames, mjai events, bot meta)