cspell-sync
Your custom words. Everywhere. Automatically.
A VS Code extension that keeps cSpell custom words in sync between every project and the global dictionary, in both directions. Words added in one project reach the global list a second after the settings file is saved, so opening a new project no longer means red squiggles under your whole technical vocabulary.
Built with
Highlights
- ▸Reads from four sources — project settings, custom dictionaries, language-specific settings and combined.txt drop files — and merges them into the global word list.
- ▸Bidirectional: global words can be pushed back into a project, workspace, existing dictionary or a new dictionary file.
- ▸A watcher on .vscode/settings.json with a fixed one-second debounce syncs a newly added word a second after the file is saved.
- ▸Bundles to roughly 19 KB minified with zero runtime npm dependencies, and activates on onStartupFinished so it never delays editor startup.
Design constraints
- ▸Activation on onStartupFinished — a spell-checker helper must never be on the startup critical path.
- ▸A two-tier cache — 60 seconds for extension configuration, 30 seconds for parsed settings.json — so unchanged JSON is not reparsed on every read.
- ▸Incremental sync that processes only the changed settings file rather than every workspace folder.
From the README
cSpell Sync
Your custom words. Everywhere. Automatically.
Project → Global · Global → Project · Custom Dictionaries · File Watchers · Zero Config
The Problem
You add custom words to .vscode/settings.json in each project. Switch to a new project and you're back to red squiggles on your entire technical vocabulary — every framework name, every company term, every acronym you've ever typed. You add them again. And again.
cSpell Sync fixes that. Install once, and every word you've ever added to any project flows automatically into your global dictionary. Open any project: zero red squiggles on known terms.
STAR
Situation — Developers working across multiple VS Code projects accumulate custom words in project-specific .vscode/settings.json files. These words are siloed: opening a new project means red squiggles on your entire technical vocabulary — framework names, company terms, acronyms — even though you've already accepted them dozens of times in other projects.
Task — Build a VS Code extension that keeps cSpell.words in sync across all open projects and the global dictionary, automatically and bidirectionally, with zero manual effort after install.
Action — Developed a lightweight extension that activates on startup, reads from four sources (project settings, custom dictionaries, language-specific settings, combined.txt drop files), and merges them into cSpell.userWords globally. Added a file watcher on .vscode/settings.json with a fixed one-second debounce, so new words sync a second after the file is saved. Bidirectional sync pushes global words back to projects via keyboard shortcut or automatically. The entire extension bundles to a single ~19 KB minified JS file with zero runtime dependencies.
Result — Open any project and your full vocabulary is instantly available. Custom words added in one project propagate globally a second after the settings file is saved. Zero red squiggles on known terms across all projects, with a status bar indicator and optional output-channel logging for transparency.
Google XYZ
- Accomplished zero red squiggles on first project open by syncing all project dictionaries to the global
cSpell.userWordson startup, as measured by deduplication and alphabetical merge of the word list, by reading from four configurable sources in parallel per workspace folder. - Built bidirectional sync between global dictionary and project settings, as measured by support for four sync targets (project
.vscode/settings.json, workspace settings, existing custom dictionary, new dictionary file), by watchingcSpell.userWordsconfiguration changes and responding within one debounce cycle. - Engineered one-second incremental sync with a debounced file watcher and a two-tier cache (60 s for extension configuration, 30 s for parsed
settings.json), as measured by processing only the changed settings file rather than all workspace folders.
By the Numbers
| Metric | Value |
|---|---|
| Sync sources | 4 (project settings, custom dicts, language settings, combined.txt) |
| Sync targets | 4 (project settings, workspace settings, existing custom dictionary, new dictionary file) |
| Bundle size | ~19 KB minified (19,052 bytes in the v1.1.0 VSIX) — zero runtime npm dependencies |
| Startup overhead | One pass over all four sources per workspace folder, initialSyncDelay (5 s) after activation |
| Activation event | onStartupFinished — never delays editor startup |
| Cache TTLs | 30 s for parsed settings.json, 60 s for extension configuration |
Install
VS Code:
ext install VKrishna04.cspell-sync
Or search cSpell Sync in the Extensions panel (Ctrl+Shift+X).
Cursor / Windsurf / VSCodium / other Open VSX editors:
Install from Open VSX or search cSpell Sync in the editor's extensions panel.
Commands
| Command | Shortcut | Description |
|---|---|---|
| Sync Projects → Global | Ctrl+Alt+S / Cmd+Alt+S | Push all project words into global dictionary |
| Sync Global → Projects | Ctrl+Alt+G / Cmd+Alt+G | Push global words back to project settings |
| Sync Custom Dicts → Global | (Command Palette only) | Push custom dictionary words to global |
All commands are also accessible via the Command Palette (F1 → type cSpell Sync).
A status bar item ($(sync) cSpell Sync) appears in the bottom-right and triggers the project→global sync on click.
Configuration
General
| Setting | Type | Default | Description |
|---|---|---|---|
cspell-sync.autoSyncOnStartup | boolean | true | Auto-sync project → global when VS Code starts |
cspell-sync.initialSyncDelay | number | 5000 | Milliseconds to wait before startup sync |
cspell-sync.showNotifications | boolean | true | Show info notifications after sync |
cspell-sync.logToOutputChannel | boolean | false | Log detailed operations to Output panel |
Sources (Project → Global)
| Setting | Default | Description |
|---|---|---|
cspell-sync.syncProjectSettings | true | Sync from cSpell.words in .vscode/settings.json |
cspell-sync.syncCustomDictionaries | true | Sync from cSpell.customDictionaries entries |
cspell-sync.syncLanguageSettings | true | Sync from cSpell.languageSettings[].words |
cspell-sync.syncCombinedTxt | true | Process combined.txt drop files |
cspell-sync.customToGlobalSync | false | Include custom dicts in the main project→global sync |
Bidirectional Sync (Global → Project)
| Setting | Default | Description |
|---|---|---|
cspell-sync.bidirectionalSyncMode | "shortcut" | shortcut · automatic · disabled |
cspell-sync.projectLevelSync.enabled | true | Write to .vscode/settings.json |
cspell-sync.projectLevelSync.target | "cSpell.words" | Target key in settings.json |
cspell-sync.workspaceSync.enabled | false | Write to workspace .code-workspace |
cspell-sync.customDictionarySync.enabled | false | Write to an existing custom dictionary |
cspell-sync.newDictionarySync.enabled | false | Create a new dictionary file |
Working with combined.txt
Drop a combined.txt file with one word per line (or comma/space separated) and its words are added to your global dictionary. Useful for bulk-importing word lists without editing settings files directly.
A file watcher picks up newly created combined.txt files anywhere in the workspace. The startup and manual syncs only look for combined.txt in each workspace folder's root.
When the watcher sees a new file and showNotifications is on, you are prompted to Process and Remove or Keep. Processing adds the words and deletes the file — there is no process-and-keep. With notifications off, or when the file is picked up by a startup or manual sync instead of the watcher, it is processed and deleted without a prompt.
Choosing Keep writes the following into that folder's .vscode/settings.json, which makes the extension skip combined.txt in that folder entirely — the file stays and its words are not synced:
{ "cspell-sync.combined-auto-remove": false }
How words are merged
Every sync is additive. Words not already present are appended and the whole list is re-sorted alphabetically (case-insensitive); nothing is removed or overwritten on either side. Global→project sync writes .vscode/settings.json with JSON.stringify(…, null, 4), so comments and custom formatting in that file are not preserved.
Workflows
Basic — Open any project → words from .vscode/settings.json merge into your global dictionary automatically.
Team dictionary — Enable customDictionarySync, point it at a shared .txt or .json dict in your repo, run Ctrl+Alt+G to push your global words into it, commit. Teammates get the words on pull.
New project bootstrap — Enable newDictionarySync, set a name. Running Ctrl+Alt+G creates dictionaries/project-dictionary.json and registers it in .vscode/settings.json automatically.
For More Information
- GitHub Repository — source code, issues, PRs
- CHANGELOG — version history
- Issue Tracker — bug reports and feature requests