Pace

Learn vocabulary through conversation, not flashcards.

Pace is a CLI tool powered by Claude that turns natural dialogue into spaced repetition. Just talk about words you encounter — Pace defines them, saves them, and quizzes you at optimal intervals using the Leitner system.

$ pace
Pace — vocab trainer. Just talk, or say "drill" to review.

❯ I came across "pernicious" in an article today

Pernicious (adj.) — having a harmful effect, especially in a gradual
or subtle way.
"The pernicious influence of tabloid journalism."
+added to Box 1

❯ let's drill

3 cards due (Box 1: 2, Box 2: 1)

[Box 1] What does "pernicious" mean?

❯ something harmful

Correct — harmful, especially gradually. → Box 2 (review in 2 days)

Prerequisites

• Bun (v1.0+)
• An Anthropic API key (set ANTHROPIC_API_KEY in your environment)

Install

git clone <repo-url> && cd pace
bun install
bun link

pace is now available globally.

Usage

pace                          # Start a conversation (default)
pace -w [port]                # Start web UI (default port 3000)
pace drill [deck] [--tag T]   # Self-evaluated drill session
pace stats                    # Box breakdown + streak
pace list                     # All saved words
pace due [deck] [--tag T]     # Cards due for review
pace progress [days]          # Progress report (default 30 days)
pace set <key> <value>        # Set a preference (name, native_language, etc.)
pace config                   # Show current config

Adding words

Just mention a word in conversation. Pace defines it, saves it to Box 1, and schedules it for review. You can also paste a paragraph — Pace will suggest interesting words to learn.

Track where you found words:

❯ I heard "epistemology" on the Lex Fridman podcast

Epistemology (noun) — the branch of philosophy concerned with
the nature and scope of knowledge.
+added to Box 1 (source: Podcast: Lex Fridman)

Drilling

Pace quizzes you on due cards, weakest first. Accept close paraphrases — you can override if Pace misjudges:

❯ actually I got that wrong

Got it — "leverage" back to Box 1.

Or use the standalone drill mode (no Claude, self-evaluated):

pace drill            # All due cards
pace drill english    # Just the "english" deck
pace drill --tag gre  # Just words tagged "gre"

Organization

Words go to the inbox deck by default. Organize with decks and tags:

❯ put pernicious and insidious in my reading deck

Moved 2 words to "reading" deck.

pace tag volatile science everyday
pace tags                             # List all tags with counts
pace decks                            # List all decks

Importing words

pace import words.json

Expected format:

[
  {
    "word": "example",
    "definition": "a thing used to illustrate a rule",
    "pos": "noun",
    "examples": ["for example, ..."],
    "synonyms": ["instance"],
    "deck": "english",
    "source": "Book: Elements of Style"
  }
]

Only word and definition are required. Duplicates are skipped.

Preferences

Pace remembers your name, native language, and conversation preferences across sessions. On your first conversation, it asks — or set them directly:

pace set name Victor
pace set native_language 中文
pace config                   # Show all preferences

Stored in ~/.pace/config.json. Pace uses your native language to draw connections when explaining words.

Session tracking

For LLM-driven drill workflows (e.g. from Claude Code), Pace supports granular session logging:

pace session 3 2                    # Record session: 3 reviewed, 2 correct
pace log word 1 --accuracy 4 \
  --spelling 5 --context 3 \
  --session 7                       # Log per-card scores (0-5)
pace insight 7 "Good on concrete words" \
  --strengths '["recall"]' \
  --weaknesses '["abstract terms"]' # Session summary
pace insights                       # Recent session insights
pace history <word>                 # Review history for a word

Claude Code Skills

Pace ships with Claude Code slash commands for AI-driven drill sessions. Install them to your user scope so they work from any directory:

cp -r .claude/skills/drill ~/.claude/skills/
cp -r .claude/skills/vocab ~/.claude/skills/

Then in any Claude Code session:

• /drill — Interactive drill session. Claude quizzes you on due cards, evaluates your answers conversationally, and logs per-card scores and session insights.
• /drill --tag gre — Drill only words with a specific tag.
• /vocab pernicious — Define and save a word.
• /vocab then paste a paragraph — Claude suggests interesting words to learn and adds the ones you pick.
• /bump-version [patch|minor|major] — Bump version, update changelog, commit, and tag.

How it works

Pace uses the Leitner spaced repetition system with 6 boxes:

Box	Interval	Meaning
1	Every session	New or failed words
2	2 days	Initial recall
3	1 week	Short-term
4	2 weeks	Medium-term
5	1 month	Long-term
6	Retired	Mastered

Correct answer = promote to next box. Wrong answer = back to Box 1.

Data

Everything is stored locally in ~/.pace/:

• pace.db — SQLite database (words, stats, reviews, insights)
• config.json — user preferences (name, native language)

No data leaves your machine except the conversation with Claude's API.

Development

bun install              # Install deps
bunx tsc --noEmit        # Type check
bun run src/cli.ts       # Run directly (without linking)
bun link                 # Make `pace` available globally

License

MIT