WordSlash

📚 Build Your English Learning Loop in VS Code

Select to Learn · Flashcard Review · SM-2 Spaced Repetition · Never Lose Data

Installation • Quick Start • Configuration • MCP Server • Commands

English | 中文

---

✨ Features

• 🎯 Seamless Integration - Add any word/phrase to flashcards with a single click while coding
• 🔄 Scientific Review - SM-2 spaced repetition algorithm for efficient memorization
• 📊 Visual Dashboard - Heatmap, donut charts, and progress tracking
• 🔊 Text-to-Speech - Multiple TTS engines for pronunciation practice
• 💾 Data Safety - Local JSONL storage with event sourcing, export/import support
• 🤖 AI Integration - MCP Server for Claude Desktop and other AI assistants

---

📦 Installation

From VS Code Marketplace

1. Open VS Code
2. Press Ctrl+Shift+X (Windows/Linux) or Cmd+Shift+X (macOS)
3. Search for "WordSlash"
4. Click Install

From VSIX File

1. Download the .vsix file from GitHub Releases
2. Open VS Code
3. Press Ctrl+Shift+P / Cmd+Shift+P
4. Type "Install from VSIX" and select the downloaded file

From Source

git clone https://github.com/talkincode/wordslash.git
cd wordslash
npm install
npm run compile
# Press F5 in VS Code to launch Extension Development Host

---

🚀 Quick Start

1. Add a Card

1. Select any word or phrase in the editor
2. Right-click and choose "Add to WordSlash"
3. The card is created with context from the current line

💡 If nothing is selected, the word under cursor is automatically extracted

2. Start Learning

• Click the WordSlash icon in the Activity Bar (sidebar)
• Or press Ctrl+Shift+P / Cmd+Shift+P → "WordSlash: Open Flashcards"

3. Review Cards

Button	Meaning	Effect
Again	Don't remember	Flip to back, reset interval
Hard	Barely remember	Flip to back, short interval
Good	Remember	Next card, normal interval
Easy	Very familiar	Next card, extended interval
Reveal	Want to see back	Flip (not scored)

---

⚙️ Configuration

Open VS Code Settings (Ctrl+, / Cmd+,) and search for wordslash:

General Settings

Setting	Type	Default	Description
wordslash.newCardsPerDay	number	20	Maximum new cards per day
wordslash.privacy.storeFilePath	boolean	false	Store source file path in cards

Text-to-Speech (TTS)

Setting	Type	Default	Description
wordslash.tts.engine	string	youdao	TTS engine: youdao, google, browser, azure, openai
wordslash.tts.rate	number	1.0	Speech rate (0.5-2.0)
wordslash.tts.autoPlay	boolean	true	Auto-play pronunciation on card appear
wordslash.tts.azureKey	string	-	Azure Speech API key (for azure engine)
wordslash.tts.azureRegion	string	eastus	Azure region
wordslash.tts.openaiKey	string	-	OpenAI API key (for openai engine)

TTS Engine Comparison

Engine	Quality	Offline	API Key Required
Youdao	⭐⭐⭐⭐	❌	No
Google	⭐⭐⭐	❌	No
Browser	⭐⭐	✅	No
Azure	⭐⭐⭐⭐⭐	❌	Yes
OpenAI	⭐⭐⭐⭐⭐	❌	Yes

---

📋 Commands

Press Ctrl+Shift+P / Cmd+Shift+P to open the Command Palette:

Command	Description
WordSlash: Open Dashboard	Open the full dashboard with charts and statistics
WordSlash: Open Flashcards	Open the flashcard review interface
WordSlash: Add Card from Selection	Create a card from selected text
WordSlash: Export Backup	Export all data to a backup file
WordSlash: Import Backup	Import data from a backup file
WordSlash: Import Cards from JSON	Bulk import cards from JSON file
WordSlash: Export JSON Template	Export a template for bulk import
WordSlash: Open Settings	Open WordSlash settings

---

💾 Data & Backup

Storage Location

Data is stored in VS Code's globalStorage:

• macOS: ~/Library/Application Support/Code/User/globalStorage/wordslash.wordslash/
• Windows: %APPDATA%/Code/User/globalStorage/wordslash.wordslash/
• Linux: ~/.config/Code/User/globalStorage/wordslash.wordslash/

Data Files

File	Description
cards.jsonl	Vocabulary cards (append-only)
events.jsonl	Review events (immutable history)
index.json	Rebuildable cache

Export & Import

# Export backup
Ctrl+Shift+P → WordSlash: Export Backup → Choose directory

# Import backup
Ctrl+Shift+P → WordSlash: Import Backup → Select backup file

💡 Import is idempotent - same backup imported twice won't create duplicates

---

🤖 MCP Server

WordSlash includes an MCP (Model Context Protocol) Server that allows AI assistants like Claude Desktop, VS Code Copilot, and other MCP-compatible clients to manage your vocabulary cards through natural language.

What is MCP?

MCP (Model Context Protocol) is an open protocol that enables AI assistants to interact with external tools and data sources. With WordSlash MCP Server, you can:

• 📝 Add vocabulary cards by simply chatting with AI
• 🔍 Search and browse your word collection
• ✏️ Update cards with synonyms, antonyms, examples
• 📊 View statistics and learning progress
• 🕸️ Explore relationships between words

Quick Start with npx (Recommended)

The easiest way to use WordSlash MCP - no installation required!

Claude Desktop Configuration

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%/Claude/claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "wordslash": {
      "command": "npx",
      "args": ["-y", "wordslash-mcp"]
    }
  }
}

With Custom Storage Path

{
  "mcpServers": {
    "wordslash": {
      "command": "npx",
      "args": ["-y", "wordslash-mcp"],
      "env": {
        "WORDSLASH_STORAGE_PATH": "/path/to/your/wordslash/data"
      }
    }
  }
}

💡 Tip: To share data with VS Code extension, set WORDSLASH_STORAGE_PATH to:

• macOS: ~/Library/Application Support/Code/User/globalStorage/wordslash.wordslash
• Windows: %APPDATA%/Code/User/globalStorage/wordslash.wordslash
• Linux: ~/.config/Code/User/globalStorage/wordslash.wordslash

VS Code Integration

For VS Code with GitHub Copilot Chat or Continue extension, add to your MCP settings:

{
  "mcpServers": [
    {
      "name": "wordslash",
      "command": "npx",
      "args": ["-y", "wordslash-mcp"]
    }
  ]
}

Available Tools

Tool	Description
create_card	Create a vocabulary card with term, translation, phonetic, examples, synonyms, antonyms, tags
list_cards	List all cards with optional search term or tag filter
get_card	Get a single card by ID or term
update_card	Update card fields (translation, examples, synonyms, etc.)
delete_card	Soft delete a card
delete_cards_batch	Batch delete by IDs, search term, or tag
list_events	View review history (learning events)
get_index	Get index status (total cards, due cards, new cards)
get_dashboard_stats	Get comprehensive statistics (retention rate, streak, etc.)
generate_knowledge_graph	Generate vocabulary relationship graph

Usage Examples

Adding a Word

You: Add "ephemeral" - it means "短暂的", example: "Fame is ephemeral."

Claude: I'll create a vocabulary card for "ephemeral".
✓ Created card:
  - Term: ephemeral
  - Translation: 短暂的
  - Example: Fame is ephemeral.

Adding with Full Details

You: Add "ubiquitous" with:
- Translation: 无处不在的
- Phonetic: /juːˈbɪk.wɪ.təs/
- Example: "Smartphones have become ubiquitous."
- Synonyms: omnipresent, pervasive
- Tags: GRE, tech

Claude: ✓ Created card for "ubiquitous" with all details!

Searching Cards

You: Show me all my GRE words

Claude: Found 15 cards with tag "GRE":
1. ephemeral - 短暂的
2. ubiquitous - 无处不在的
3. pragmatic - 务实的
...

Updating a Card

You: Add synonyms "fleeting, transient" to ephemeral

Claude: ✓ Updated "ephemeral" with new synonyms!

Checking Progress

You: How's my vocabulary learning going?

Claude: Here's your learning stats:
📊 Total Cards: 156
📅 Due Today: 12
🔥 Streak: 7 days
🎯 Retention Rate: 85%
✅ Mastered: 45 cards

Environment Variables

Variable	Description	Default
WORDSLASH_STORAGE_PATH	Custom storage directory	~/.wordslash (standalone) or VS Code globalStorage

---

🧠 SM-2 Algorithm

WordSlash uses the classic SM-2 spaced repetition algorithm:

Rating	Quality	Interval Effect
Again	q=0	Reset to 1 day, increment lapses
Hard	q=3	Short interval
Good	q=4	Normal interval
Easy	q=5	Extended interval

The algorithm dynamically adjusts review intervals based on your performance, optimizing long-term retention.

---

🛠️ Development

# Clone repository
git clone https://github.com/talkincode/wordslash.git
cd wordslash

# Install dependencies
npm install

# Compile
npm run compile

# Run tests
npm test

# Watch mode
npm run watch

# Debug in VS Code
# Press F5 to launch Extension Development Host

Project Structure

wordslash/
├── src/
│   ├── extension.ts        # Extension entry point
│   ├── commands/           # VS Code commands
│   ├── storage/            # JSONL storage, indexer, schema
│   ├── srs/                # SM-2 algorithm, scheduler
│   └── webview/            # Dashboard, Flashcards UI
├── scripts/
│   └── mcp-server/         # MCP Server for AI integration
├── media/                  # Icons and assets
└── package.json

---

🗺️ Roadmap

• v0.1 - Core loop: commands, storage, flashcards, SM-2
• v0.2 - Dashboard, heatmap, charts, MCP server
• v0.3 - Experience: keyboard shortcuts, batch operations
• v0.4 - AI: LLM-powered card content generation

---

📄 License

MIT License - see LICENSE for details.

🤝 Contributing

Issues and Pull Requests are welcome!

---

Made with ❤️ for learners who code