Questions that may come up before installing
Who is kamishibai for?
For people ready to practice spaced repetition regularly and for a long time — months, not a couple of evenings. kamishibai is not a course. It doesn't pick topics or walk you through a syllabus: you bring the words you happened to meet in a book, in subtitles or in conversation, and kamishibai turns them into cards.
From there Anki takes over: it decides how many cards to show today and keeps the daily session from ballooning. The intervals between reviews gradually grow — from a couple of days to weeks and months.
What can I feed it?
The main path is a word list: you pick the meanings you need, and kamishibai writes a new phrase for each one. If the card content is already written, pass it in as cards JSON: the fields can hold anything as long as the schema checks out — kamishibai adds the audio and pictures itself.
What does Anki do, and what does kamishibai do?
kamishibai prepares the cards and packs them into an .apkg file — the import format for Anki. Anki schedules the reviews and keeps your answer grades. If you want physical cards, kamishibai also produces a PDF: print it and cut it up.
Do I need to know how to program?
No. The main mode is a step-by-step TUI in the terminal: you paste words, pick meanings, review cards and get your deck. The JSON CLI exists only for scripts and external agents.
Who decides what ends up on a card?
You do. In the terminal you work with your own words: you pick the meanings and decide which cards to keep. The same work can be delegated to an agent, but reviewing the result still stays with you.
Which languages are supported?
EN, ZH, ES, JA, FR, DE, RU, IT, PT, EL and NL — in any pairing. One run works with one pair. Not every combination is one the models know equally well. If you need another language, open an issue on GitHub — let's see what can be done.
What do I need before the first run?
A computer, an internet connection during generation and your own Gemini API key — you can create one in Google AI Studio → For reviews you need Anki → On the first illustration run kamishibai downloads its OCR models.
What systems does it run on?
Prebuilt binaries are available for macOS, Linux and Windows. Homebrew works on macOS and Linux. The shell installer also runs in Git Bash, MSYS or Cygwin on Windows.
How much does it cost?
kamishibai itself is free and open source, but the Gemini requests are billed to your key. Generating 100 cards comes to roughly $15. That's a rough estimate: the total depends on how many cards need regenerating. You don't have to choose models, they're already configured: I try to keep them current but reasonably priced, and I put card quality above minimal token spend.
A hundred cards means 100 full phrases and several hundred words in context — usually a month or two of learning. So kamishibai is best spent on words that genuinely matter to you.
Where do my words and my key go?
Sessions, cache and finished files live on your disk. kamishibai has no server of its own. Generation goes through Gemini with your key, so words and phrases do leave your machine. The saved key sits in a local settings file, not in the system keychain.
Can the generated material be wrong?
Yes. The model can pick the wrong shade of meaning or slip in the IPA, and the audio can come out badly. kamishibai checks the quality and style of the illustrations itself and retries the failures — up to three attempts are built in, so sometimes more tokens get spent. In rare cases a word can exhaust all attempts and end up without a card. Check the deck before you start reviewing.
What exactly does Agent Ready mean?
It means the tool can be used not only by a human but by an agent like Claude Code. The JSON CLI commands — new, select or exclude, generate, status, result — need no interactive input and return machine-readable output, so an agent can call them asynchronously and run several sessions in parallel. How to use the commands is described in llms.txt — just show the agent that file.
You can hand an agent:
- building a word list for a specific goal,
- picking the meanings,
- checking the finished cards before import.
This is handy at volume, but extra checks and regenerations increase token spend and cost.
Why would I bring my own JSON?
Your own cards JSON is for when the wording must be entirely yours: ready-made sentences, mini-dialogues, phrases from a lesson. Pass in the content — kamishibai adds audio and illustrations, then builds the APKG and PDF. The strict schema is in cards-json.md →
Can I review on my phone?
Generation runs on a computer. After that, double-clicking the .apkg file is usually enough: Anki opens and starts the import (if not, use File → Import). Syncing the deck to your phone is Anki's job.
The PDF has no schedule, but it makes real paper cards: print, cut, fold. The most important or stubborn phrases can sit on your desk — without the audio, admittedly.
Who creates the text, audio and illustrations?
The text, audio and illustrations are generated by models of the Gemini family.
What if a card just won't come back to me?
Press "Again" and move on. Tune the strictness of your grading to your level. Early on you can accept an answer with a wrong article or preposition, as long as you remember the meaning of the phrase and its key words. Once the first 50 phrases sit well, raise the bar.
If months later a familiar card suddenly escapes you, press "Again": it's often exactly after such a miss that a phrase sticks for good.
When can I expect results?
After the first 50 well-learned phrases the effect starts to show: familiar constructions come back more easily, and little by little a feel for the language appears — at least in the area those phrases came from.