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

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

From VSIX File

Download the .vsix file from GitHub Releases
Open VS Code
Press Ctrl+Shift+P / Cmd+Shift+P
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

Select any word or phrase in the editor
Right-click and choose "Add to WordSlash"
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

[x] v0.1 - Core loop: commands, storage, flashcards, SM-2
[x] 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

WordSlash

TeraTeams

WordSlash

✨ Features

📦 Installation

From VS Code Marketplace

From VSIX File

From Source

🚀 Quick Start

1. Add a Card

2. Start Learning

3. Review Cards

⚙️ Configuration

General Settings

Text-to-Speech (TTS)

TTS Engine Comparison

📋 Commands

💾 Data & Backup

Storage Location

Data Files

Export & Import

🤖 MCP Server

What is MCP?

Quick Start with npx (Recommended)

Claude Desktop Configuration

With Custom Storage Path

VS Code Integration

Available Tools

Usage Examples

Adding a Word

Adding with Full Details

Searching Cards

Updating a Card

Checking Progress

Environment Variables

🧠 SM-2 Algorithm

🛠️ Development

Project Structure

🗺️ Roadmap

📄 License

🤝 Contributing