# Akagi: a real-time mahjong assistant that reads your game state and tells you what to discard

> A single-binary Rust and Tauri rewrite of a mahjong AI helper that sits beside Mahjong Soul, Tenhou and Riichi City and puts shanten, deal-in risk and a suggested discard on screen while you play.

**shinkuan/Akagi** — Supports Majsoul, Tenhou, Riichi City, and Amatsuki, with the ability to use custom AI models to analyze games in real time and provide suggestions. Comes with Mortal AI as a built-in example.

- Repository: https://github.com/shinkuan/Akagi
- Website: https://akagi.shinkuan.me/
- Stars: 1,088 · Forks: 137
- Language: Rust
- License: Apache-2.0
- Published: 2026-10-07 · Updated: 2026-10-07 · Language: en
- Canonical page: https://hysenlabs.com/projects/shinkuan-akagi

## What the live HUD actually puts on screen

The feature list at the top of the README is specific enough to be worth reading closely. The HUD shows shanten, waits, agari rate, tenpai rate, per-opponent deal-in risk, and a suggested discard that separates into an attack option and a defence option. That last split is the piece that distinguishes this from a simple tile-efficiency calculator: the deal-in risk figure is computed per opponent rather than as one number for the table, so a discard that is safe against one player and dangerous against another can be presented as such.

The layout is draggable and resizable, which sounds like a small feature until you consider that the overlay sits on top of a game client. Anything that forces a fixed position eventually ends up covering the tiles you need to see.

The stated purpose of the project is understanding your own performance in real time and learning from it, and the README carries an explicit educational-purpose disclaimer that also points out game publishers reserve the right to act against users who violate their terms of service, with consequences such as account suspension left to the user. That is an unusually direct statement, and it is the single most important thing to weigh before installing anything here.

## Two ways to capture game state, and why the default needs a certificate

Akagi offers two capture modes. The MITM proxy is the default: it installs a local proxy that intercepts traffic system-wide, which means the machine's certificate authority has to trust it once. The alternative is a Chromium path where Akagi launches a controlled Chromium-family browser itself rather than attaching to whatever browser you already use.

The distinction matters more than it first appears. A system-wide MITM proxy sees all traffic on the machine, not just the game's, so trusting its certificate is a broader change to the host than it is to a single browser profile. The Chromium route keeps the interception inside a browser instance the app controls, at the cost of having to play in that browser instance. For a shared or managed machine, the second is usually the one you want, and it is worth deciding before first launch rather than after.

The first-run setup is a fixed sequence: language, then platform, then capture mode, then the certificate trust or Chromium pick, then bot settings. The app ships in English, Japanese, Traditional Chinese and Simplified Chinese, and the language can be switched live from Setup or Settings.

The repository also shows how seriously the interception side is taken. Release v3.6.1 added blocking for Aliyun SLS telemetry beacons, and v3.7.0 added telemetry blocking for Riichi City along with autoplay and full-auto sessions. The same v3.7.0 release added a whole-game review page marked as Beta, and recorded the match room, rank lobby and game id per game so that history entries can be traced back to a specific session.

## A bundled Rust model plus optional cloud inference

Akagi ships with an AI model inside the application. The README is explicit that nothing needs installing, and that the suggestion appears each turn. The bundled backend is the pure-Rust one in the repository, and the tree shows the pieces it lives in: `native_bot/` for the embedded model, `mjai_bot/` for the plugin interface the bot protocol expects, and `runtime/` for whatever executes them.

When the bundled model is not enough, the alternative is a cloud inference API. Release v3.6.1 made the inference reaction timeout configurable with a default of 3000ms, which tells you something real about the trade. A cloud endpoint can return a stronger recommendation but adds a network round trip to a decision that has to land inside a turn timer. A three-second default is generous for a hint you read, and expensive for an automated action you do not.

The dependencies listed in `Cargo.toml` line up with that design. Beyond `tauri` version 2 there is `tokio` with the multi-threaded runtime and process features, `clap` for argument parsing, `async-trait` for the bot plugin boundary, `serde` and `serde_json` for the game state that crosses it, and `which` for locating a browser executable. There is also `prost-build` in the build dependencies, which points at protocol buffer definitions compiled at build time rather than hand-written parsing.

One dependency choice deserves a note because it explains a shipping decision. `toml_edit` is present specifically so saving `config.toml` preserves keys the running build does not recognise, including keys written by a different Akagi version or added by the user. Serialising the file with a plain TOML writer would delete them. That is a small thing to get right and a common thing to get wrong in desktop apps.

## Building from source and the macOS packaging trade

Akagi V3 is a rewrite of the older Python version, which lives on the `v2` branch, and of an Electron fork called Akagi-NG. The default branch is `v3`, and the current version in `Cargo.toml` is 3.7.1 with edition 2021.

Two build details are documented in `Cargo.toml` comments rather than in prose, which makes them easy to miss. First, there is a `custom-protocol` feature. Without it, Tauri builds in dev mode and the window loads the Vite dev server instead of the embedded frontend, so a plain release build shows a refused connection on localhost. `cargo tauri build` passes the feature automatically; a plain Cargo build has to ask for it.

Second, the Tauri dependency enables `macos-private-api`. The suggestion overlay is a transparent window, and the transparency call on macOS is only compiled when that feature is on, gated in the source behind a target check. The cost is stated plainly in the same comment: it uses private Apple APIs, so a build with it cannot be accepted into the Mac App Store. Since Akagi distributes as an unsigned portable zip from GitHub Releases, that cost is currently zero.

The dependency block also shows the ordinary Rust stack of a desktop app with real work to do:

```toml
custom-protocol = ["tauri/custom-protocol"]
tauri = { version = "2", features = ["macos-private-api"] }
serde = { version = "1", features = ["derive"] }
toml_edit = "0.25"
clap = { version = "4.6", features = ["derive"] }
```

Updates are handled in-app. The app checks for new releases on launch and on demand from Settings, then downloads, applies and restarts in one step, with read-only installs such as the AppImage format falling back to opening the release page instead. A `minisign.pub` key in the tree indicates the release artifacts are signed.

## Three-player support and the history tab

Sanma, the three-player variant, is supported throughout rather than as an afterthought. Analysis works, history stats work, and the tables account for three-player uma. The routing mechanism is two config keys, `bot.active_4p` and `bot.active_3p`, which swap automatically based on the player count at the table. That is the whole compatibility mechanism, and it is also the thing to test first, because a bot routed to the wrong key would give advice computed for the wrong hand size.

The History tab auto-records every completed match and renders three views. There is a rank distribution pie chart, a cumulative point line chart with selectable scoring rules covering Mahjong Soul tiers, Tenhou ranks or a custom uma value, and a detailed statistics panel listing win rate, deal-in rate, riichi rate, fuuro rate, ryukyoku rate, average winning and deal-in points, average winning turn, and counts of yakuman and nagashi mangan.

Average winning turn is the least obvious number on that list and the most useful for self-improvement, since it captures how early you convert a tenpai into a win rather than just whether you won. The ranking breakdown matters for a different reason: it tells you whether a poor aggregate score is a placement problem or a speed problem.

Supported platforms are listed in a table with separate columns for four-player, three-player and autoplay support. Mahjong Soul, Tenhou and Riichi City have all three. Amatsuki is marked planned for both player counts and unsupported for autoplay.

## Where this approach stops being useful

The first limit is legal and social rather than technical. Akagi reads your own games to coach you, and the README states plainly that publishers may act against users who breach their terms, with account suspension as the user's own responsibility. No amount of local processing changes that exposure, because the traffic is still intercepted either way. Anyone playing on a ranked ladder under an account they care about is making a decision here that no feature list can make for them.

The second limit is scope. Three platforms are supported and a fourth is planned. Anything outside that list is not a configuration problem, it is missing work.

The third limit is what an assistant is not. A local model bundled for convenience will not match a hosted frontier model on long reads of an opponent's discard ordering, and the release history shows the author knows where the boundary sits: the cloud path exists, and its timeout is tunable. If you are trying to squeeze out the last few points against strong opposition, the coaching value narrows toward the parts of the game that are about your own hand, which are still substantial.

There is also a maintenance consideration specific to intercepting games. Platform clients change their wire protocols, and the v3.7.1 release is two such fixes: reading the Tenhou discard tag with the case the wire format actually defines, and surviving a mid-game rejoin that skips the opening round marker. Those are the kinds of bugs that appear without warning when a client ships an update, and they are the practical reason to install a release rather than build from a stale branch.

## Conclusion

Akagi is worth installing if you play Japanese mahjong competitively enough that knowing your shanten count and your per-opponent deal-in risk in real time would change how you play. It ships as a portable zip with the model bundled inside, so the gap between downloading it and reading your first suggestion is a CA trust step or a browser choice, not a model download. Skip it if you want an opponent-facing bot rather than a coach, if you play on Amatsuki, since that platform is still marked planned, or if your network administrator manages certificate trust centrally, because the default capture mode depends on it. Check first whether the account you use can survive a ToS challenge, which the README explicitly puts on you, then run it against the three-player tables to confirm the `bot.active_3p` routing behaves before you trust it on a ranked four-player lobby.

## FAQ

### Does Akagi need a separate AI model download?

No. The README states a built-in AI model ships inside the application, so nothing has to be installed separately and a suggestion appears each turn. A cloud inference API is available as an alternative when you want a stronger hosted model.

### Which mahjong platforms does Akagi support?

Mahjong Soul (Majsoul), Tenhou and Riichi City are listed with four-player, three-player and autoplay support. Amatsuki is marked as planned for both player counts. Three-player sanma is supported across analysis, bot routing and history.

### What is the difference between the MITM proxy and Chromium capture modes?

The MITM proxy is the default and works system-wide, which requires a one-time certificate authority trust. The Chromium mode has Akagi launch a controlled Chromium-family browser instead, keeping interception inside a browser instance the app manages.

### Can Akagi be built from source?

Yes, the repository is Rust with Tauri 2 and its default branch is v3. A plain Cargo release build needs the custom-protocol feature or the window will try to load a Vite dev server; cargo tauri build passes it automatically.

### Is using Akagi against Mahjong Soul allowed?

The README states the project is for educational purposes and that game developers and publishers reserve the right to act against users who violate their terms of service, listing account suspension as a consequence the user is responsible for.

## Sources

- [License: Apache-2.0](https://github.com/shinkuan/Akagi/blob/v3/LICENSE)
- [Project website](https://akagi.shinkuan.me/)
- [README](https://github.com/shinkuan/Akagi/blob/v3/README.md)
- [Releases](https://github.com/shinkuan/Akagi/releases)
- [shinkuan/Akagi on GitHub](https://github.com/shinkuan/Akagi)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/shinkuan-akagi