[AI Readability Summary] anki-vocab is a Python-based command-line vocabulary tool that connects Claude, OpenAI TTS, AnkiConnect, and SQLite to automate AI card generation, pronunciation audio, offline sync, and reading practice. It solves the inefficiency of manual card creation, the lack of contextual review, and the difficulty of tracking weak vocabulary. Keywords: Anki, LLM, English learning.
This tool automates card creation for serious English learners
| Parameter | Description |
|---|---|
| Language | Python 3.11+ |
| Interaction Protocol | HTTP API (AnkiConnect) |
| Repository | github.com/zhchoice123/anki-vocab |
| Project Form | CLI + local web service |
| Core Dependencies | Claude, OpenAI TTS, Flask, SQLite, Rich |
| Typical Use Cases | Word lookup and card creation, pronunciation practice, reading exercises, error tracking |
This project turns vocabulary study into a reusable AI pipeline
Traditional vocabulary apps often suffer from sparse card content, fragmented import workflows, and review modes limited to simple word-to-definition matching. The core value of anki-vocab is that it unifies lookup, content generation, audio synthesis, persistence, and practice behind a single command.
It is not just a dictionary wrapper. It acts as a learning automation hub built around Anki. After the user enters a word, the system concurrently calls the LLM and TTS services, generates a structured card and pronunciation audio, and then writes the result to Anki or a local cache automatically.
git clone https://github.com/zhchoice123/anki-vocab.git
cd anki-vocab
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env # Fill in your API keysThese commands clone the repository, initialize the virtual environment, install dependencies, and configure environment variables.
Its word lookup and card generation flow replaces most manual work
The project requires a local Anki desktop installation, the AnkiConnect plugin, and a Note Type named 英语单词模板(vocab配色). Once those prerequisites are in place, the fastest path is to run the lookup command directly.
./word tenacious
./word "give up"
./word --deck "My Deck" serenity # Specify a deck
./word --speed 0.8 verbose # Adjust pronunciation speed
./word -v tenacious # Output debug logsThese commands demonstrate common usage patterns for single words, phrases, deck selection, pronunciation speed control, and debug mode.
The system returns more than plain text. It produces a richly structured card that includes English definitions, usage scenarios, memory aids, Collins-style explanations, Chinese translations, and audio. If the word already exists, the tool reuses the existing card and pronunciation instead of calling the API again.
It embeds reading comprehension practice into real usage scenarios after memorization
Many tools stop at helping users remember a word, but the hard part of language learning is using it correctly. To address this, anki-vocab adds a practice mode. It samples words from the existing vocabulary set and then uses Claude to generate graduate entrance exam-style English reading passages and questions.
./word practice
./word practice -n 8 # Specify the number of words used for generation
./word practice --port 8767 # Change the service port
./word practice --no-browser # Do not open the browser automaticallyThese commands start the local reading practice service and let you control the number of words, the port, and browser behavior.
The generated content is typically 400 to 500 words long, split into 4 to 6 paragraphs, and followed by 5 multiple-choice questions that cover main idea, details, inference, word meaning, and attitude. The front end uses a dark theme, highlights target words, and supports hover-based quick definitions.
Its error-tracking mechanism gives weak-word review a clear priority model
The key to reading practice is not just question generation, but making mistakes feed back into future word selection. The project maps each incorrect answer back to target_word and stores it in the SQLite word_errors table.
# Pseudocode: prioritize practice words based on past mistakes
weak_words = query_words(order_by="error_count DESC, last_error DESC") # Prioritize frequently missed words
new_words = query_recent_words() # Fill the remainder with new words if needed
selected = weak_words[:10]
if len(selected) < 10:
selected += new_words[: 10 - len(selected)]This logic shows that the system first selects frequently missed words and then fills any remaining slots with recently added words.
This design avoids evenly distributed review and instead adjusts dynamically around points of forgetting, which aligns well with spaced repetition and weak-point reinforcement.
Its offline cache design keeps the workflow running even when Anki is unavailable
AnkiConnect relies on a local HTTP interface, which means card writes fail when Anki is not running. anki-vocab handles this with a fallback path: if the interface is unavailable, it temporarily stores the full card and audio Base64 payload in ~/.anki-vocab/pending.db.
[sync] synced 3 pending word(s) to AnkiThis message indicates that a background thread has pushed pending cards back into Anki.
This write-locally-first, compensate-with-later-sync strategy significantly improves fault tolerance for a CLI tool in real desktop environments and reduces the chance that external dependencies interrupt the learning flow.
The project architecture shows a clean separation of responsibilities
From the directory structure, the author splits the core capabilities into modules such as anki, llm, tts, services, practice, and display. The codebase is roughly 2,000 lines long, but it already demonstrates maintainable boundaries.
class TTSProvider:
def generate(self, word: str) -> tuple[str, bytes]:
raise NotImplementedError # Subclasses must return the filename and audio bytes
class ElevenLabsTTS(TTSProvider):
def generate(self, word: str) -> tuple[str, bytes]:
# Call a third-party TTS API
return filename, audio_bytesThis abstraction shows that the TTS layer is pluggable. You can swap providers without changing the upper-layer business flow.
The author also uses several standard engineering patterns: a Repository for Anki data access, a Decorator that adds LRU caching to queries, and a Service layer that orchestrates LLMs, TTS, storage, and display. This separation makes testing easier, simplifies provider replacement, and helps control side effects.
Round-trip serialization is one of the most valuable engineering details in this project
The project hides the full WordCard JSON inside an HTML node stored in an Anki field, then deserializes it during later queries. That means the system does not need to call the LLM again for repeated lookups. It can reconstruct the original structured object directly from Anki.
In practice, this elevates Anki from a final presentation layer to a lightweight persistence layer. It preserves compatibility with learning software while enabling reversible recovery of business objects, which makes it a practical local-first design.
The image shows a sharing prompt rather than the core technical interface
AI Visual Insight: This image is an animated sharing prompt for the platform. It primarily guides users to share content from the web interface and does not show the anki-vocab CLI output, Anki card structure, or reading practice UI, so it adds limited value to understanding the project’s technical design.
This project helps turn Anki from a card tool into a learning workflow engine
If you already use Anki but no longer want to manually look up words, copy definitions, download audio, and organize practice materials, the value of anki-vocab is straightforward. It combines LLMs, TTS, AnkiConnect, and a local practice environment into a low-friction workflow.
For users who want to extend it further, the project also offers good plug-in points, such as replacing the TTS service, adding a new LLM provider, or redesigning the reading generation strategy. It is not a demo script. It is a piece of personal learning infrastructure with room for continuous iteration.
FAQ: The three questions developers care about most
1. Will words be lost if Anki is not open?
No. When AnkiConnect is unavailable, the tool writes cards and audio to local SQLite first, then performs automatic compensating sync when a later command is triggered.
2. Why does this project have more engineering value than a typical dictionary script?
Because it does more than look up words. It completes structured generation, audio synthesis, cache reuse, Anki persistence, and reading-practice feedback in a single end-to-end workflow.
3. Can I replace the TTS or LLM provider?
Yes. The project abstracts both the TTS and LLM layers. As long as you implement the corresponding Provider interface, you usually do not need to modify upper-layer modules such as WordService.
Core Summary: anki-vocab is a Python CLI tool for Anki users that integrates word lookup, LLM-generated definitions, TTS pronunciation, Anki persistence, and reading practice into one automated pipeline, while using SQLite for offline caching and error tracking.