Anki Sorter

Frequency-first new-card ordering for Japanese sentence decks.
Make Anki introduce common, readable cards before rare or painful ones.

Why · Install · Releases · Quick start · How it sorts · Configuration · Development

---

Why

Large Japanese sentence decks can be noisy: some new cards are common and readable, while others are rare, kana-heavy, or packed with unknown kanji. Default Anki ordering does not know the difference.

Anki Sorter adds a small ranking layer before new cards are shown:

Without it	With Anki Sorter
New cards follow deck/insertion/random order.	New cards are reordered by frequency and readability.
Common but useful cards can be buried.	High-value cards rise earlier.
Unknown-kanji walls can appear too soon.	Known-kanji cards get a soft readability boost.
Reviews and learning cards risk being mixed into tooling.	Only matching new cards are repositioned.

The default setup targets Kiku and Lapis-style Japanese sentence cards. Any similar note type can work if it has an expression field and, optionally, a FreqSort fallback field.

What it does

• Frequency-first ranking — prioritizes cards with better ranks from the configured frequency source.
• Readability-aware tie breaking — prefers cards that use kanji you have already matured.
• Kiku + Lapis defaults — ships with sensible defaults for common Japanese sentence-card setups.
• Safe scope — only eligible new cards are repositioned; reviews, learning cards, and suspended cards are left alone.
• Offline fallback — uses cached/bundled data when the network is unavailable.
• Desktop-safe defaults — starts in manual mode with mobile sync guardrails for AnkiDroid workflows.
• Manual controls — sort, refresh, and switch frequency sources from Anki's Tools menu.
• Local API — exposes GET /health and POST /sort for scripts and optional timers.

Install

Install the packaged add-on from the latest GitHub Release:

1. Download anki_sorter.ankiaddon from the latest release.
   • Direct download: anki_sorter.ankiaddon
   • Do not install GitHub's source-code ZIP; use the .ankiaddon asset.
2. Open Anki Desktop.
3. Go to Tools -> Add-ons -> Install from file....
4. Select the downloaded anki_sorter.ankiaddon.
5. Restart Anki.

Release packages are built by GitHub Actions. Pull requests and pushes to main also build the .ankiaddon as a CI artifact.

For development, link the source folder into Anki's add-on directory:

# macOS
mkdir -p "$HOME/Library/Application Support/Anki2/addons21"
ln -sfn "$PWD/addon/anki_sorter" "$HOME/Library/Application Support/Anki2/addons21/anki_sorter"

# Linux
mkdir -p ~/.local/share/Anki2/addons21
ln -sfn "$PWD/addon/anki_sorter" ~/.local/share/Anki2/addons21/anki_sorter

On Windows, place or link addon/anki_sorter under %APPDATA%\Anki2\addons21\anki_sorter.

Quick start

1. Install the add-on and restart Anki.

2. Open the profile that contains your Japanese sentence deck.

3. Make sure your target cards match the scope query:

   (note:"Kiku" or note:"Lapis") is:new -is:suspended
   

4. Run Tools -> Anki Sorter -> Sort Cards Now.

5. Optional: run Tools -> Anki Sorter -> Refresh Current Frequency Source Now.

The default automation mode is intentionally manual-only:

{
  "autoSortMode": "manual_only",
  "syncSafetyMode": "mobile_guarded"
}

That means Anki Desktop does not automatically reorder after sync/profile open. This is intentional: Anki Desktop cannot detect offline AnkiDroid reviews that have not synced yet.

If you review on AnkiDroid, use this manual safe sequence before sorting:

1. Sync AnkiDroid and wait for it to finish.
2. Sync Anki Desktop and resolve any sync prompts.
3. Run Tools -> Anki Sorter -> Sort Cards Now.
4. Sync Anki Desktop again before reviewing on another device.

Use desktop_only_allow_auto only for profiles where desktop-only automatic sorting is an intentional opt-in and no phone or tablet can have unsynced reviews.

AnkiDroid sync safety

Anki Sorter repositions new cards on Anki Desktop. That can be safe only after all review devices have already pushed their latest state and Desktop has pulled it. A desktop add-on cannot inspect your phone for offline AnkiDroid reviews, so after_sync on Desktop is not a proof that the phone is current.

The safe default is:

{
  "autoSortMode": "manual_only",
  "syncSafetyMode": "mobile_guarded"
}

Only opt into desktop automation with both of these settings when the profile is genuinely desktop-only:

{
  "autoSortMode": "after_sync",
  "syncSafetyMode": "desktop_only_allow_auto"
}

AnkiDroid can help keep the phone synced, but this is hygiene rather than a correctness guarantee for desktop sorting:

• Native AnkiDroid setting: the manual says Automatic synchronization syncs "every time you open and close the app" and is limited to "once every ten minutes". It is not a time-of-day scheduler. Source: AnkiDroid manual, Preferences -> AnkiDroid -> Automatic synchronization.
• Tasker / Automate: the AnkiDroid API documents an experimental sync intent, Action:com.ichi2.anki.DO_SYNC, and warns that a "server is busy" error is shown if sync is attempted "more often than once every 5 minutes". It also says the target must be Activity, and links Tasker and Automate examples. Source: AnkiDroid API, Sync Intent.

Even with native auto-sync, Tasker, or Automate enabled, keep the manual safe sequence above when using Anki Sorter on a collection also reviewed on AnkiDroid.

How it sorts

The recommended strategy is frequency_first_soft_v1.

For each eligible new card, the add-on:

1. reads the expression field,
2. looks up a frequency rank,
3. infers known kanji from matured cards,
4. blends frequency with a soft readability multiplier,
5. repositions matching new cards through Anki's internal scheduler API.

Default scoring shape:

Card shape	Treatment
All kanji known	full frequency value
Kana-only	small configurable penalty
Unknown kanji	configurable penalty per unknown kanji
Partially-known kanji word	tiny coverage bonus

Final ordering uses score first, then raw rank, expression length, current due position, template order, and card id for stable tie-breaking.

Configuration

Open Tools -> Add-ons -> Anki Sorter -> Config inside Anki.

Recommended default core settings:

{
  "modelNames": ["Kiku", "Lapis"],
  "scopeQuery": "(note:\"Kiku\" or note:\"Lapis\") is:new -is:suspended",
  "expressionField": "Expression",
  "freqSortField": "FreqSort",
  "strategy": "frequency_first_soft_v1",
  "autoSortMode": "manual_only",
  "syncSafetyMode": "mobile_guarded"
}

Using a different but similar note type? Add it to both modelNames and scopeQuery:

{
  "modelNames": ["Kiku", "Lapis", "My Sentence Card"],
  "scopeQuery": "(note:\"Kiku\" or note:\"Lapis\" or note:\"My Sentence Card\") is:new -is:suspended"
}

Important settings:

Setting	Purpose
modelNames	Note types the sorter is allowed to touch.
scopeQuery	Anki search query for eligible new cards.
matureDays / matureQuery	Which cards count as known-kanji evidence.
expressionField	Field containing the Japanese expression.
freqSortField	Optional deck-provided frequency fallback.
autoSortMode	after_sync, profile_open, or manual_only.
syncSafetyMode	mobile_guarded by default; desktop_only_allow_auto opt-in for automation.
jitenFrequencyListId	Built-in Jiten list: global, visual_novel, novel, anime, etc.
yomitanFrequencyIndexUrl	Optional Yomitan frequency dictionary URL.

Frequency sources

By default, the add-on uses Bee's updateable Yomitan frequency dictionary and falls back to cached/bundled data when needed. You can switch to a built-in Jiten list from:

Tools -> Anki Sorter -> Choose Jiten Frequency List...

Attribution: frequency data is derived from Jiten. Jiten frequency data is licensed under CC BY-SA 4.0. Keep addon/anki_sorter/data/ATTRIBUTION.md with redistributed packages.

Menus and API

Anki menu actions:

• Tools -> Anki Sorter -> Sort Cards Now
• Tools -> Anki Sorter -> Choose Jiten Frequency List...
• Tools -> Anki Sorter -> Set Yomitan Frequency Dictionary URL...
• Tools -> Anki Sorter -> Clear Yomitan Frequency Dictionary URL
• Tools -> Anki Sorter -> Refresh Current Frequency Source Now

Local endpoints while Anki is running:

curl http://127.0.0.1:8767/health
curl -X POST http://127.0.0.1:8767/sort

Optional helper script:

python3 scripts/request_sort.py --force

Deck behavior

The add-on repositions new cards. It does not touch review or learning cards, and it does not override Anki's scheduler.

For the sorted order to show reliably, deck options should preserve gathered order. /health reports warnings when deck options look incompatible with manual repositioning.

Optional systemd timer

The default manual_only mode is safest for desktop + AnkiDroid workflows. If you still want a timer, templates live in systemd/:

mkdir -p ~/.config/systemd/user
cp systemd/anki-sorter.service ~/.config/systemd/user/
cp systemd/anki-sorter.timer ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now anki-sorter.timer

The timer only works while Anki is running and the target profile is open.

Development

Run the test suite:

python3 -m unittest discover -s tests

Compile check:

python3 -m compileall addon scripts tests

Rebuild the add-on package:

python3 scripts/package_addon.py

Repo layout:

Path	Purpose
addon/anki_sorter/	Anki add-on source.
addon/anki_sorter/data/	Bundled fallback frequency data and attribution.
scripts/package_addon.py	.ankiaddon package builder.
scripts/request_sort.py	Optional local API helper.
systemd/	Optional user timer templates.
tests/	Unit tests.

Troubleshooting

If sorting does nothing:

• confirm Anki is running and the correct profile is open,
• confirm target cards match scopeQuery,
• confirm each note has the configured Expression field,
• check curl http://127.0.0.1:8767/health.

If frequency ranking is missing:

• run Tools -> Anki Sorter -> Refresh Current Frequency Source Now,
• confirm the configured Yomitan/Jiten source can be reached,
• confirm bundled snapshots are present under addon/anki_sorter/data/,
• confirm your notes have FreqSort if you rely on the deck fallback.

If the study order still looks wrong:

• inspect deck-option warnings from /health,
• make sure your deck is not randomizing new cards,
• confirm the target cards are still new after sync.