⌨️ WordVim

Vim keybindings for Microsoft Word

English · 한국어 · 日本語 · 中文

---

WordVim brings Vim's modal editing experience to Microsoft Word.

Press Escape to enter Normal mode, i to return to Insert mode — just like in Vim.

No Visual Studio required. Builds with dotnet build. One-click install.

⬇️ Download v0.1.0 · 📖 Documentation · 🚀 Quick Start

---

🎯 Why WordVim?

Microsoft Word lacks Vim's powerful modal editing. Office.js cannot intercept keystrokes — this is an architectural limitation that cannot be worked around.

WordVim solves this with native COM Add-in + Win32 keyboard hooks — the only approach that enables true Vim modal editing in Word.

┌─────────────────────────────────────────────────────────┐
│  Word: -- NORMAL --                                     │
│                                                         │
│  vim → Word integration                                │
│                                                         │
│  ✅ Modal editing (Insert/Normal/Visual)                │
│  ✅ Keyboard interception via Win32 hooks               │
│  ✅ Cursor movement via Word COM API                    │
│  ✅ One-click install — no Visual Studio needed         │
└─────────────────────────────────────────────────────────┘

✨ Features

Feature	Status
Insert / Normal mode switching	✅ Done
Mode indicator (title bar)	✅ Done
Key suppression in Normal mode	✅ Done
h/j/k/l cursor movement	🔜 Next
w/b/e word motions	🔜 Planned
x/dd/yy editing commands	🔜 Planned
Visual mode	🔜 Planned
Command-line mode (:)	🔜 Planned

🚀 Quick Start

Option 1: Download (Recommended)

Step 1: Download wordvim-v0.1.0.zip

Step 2: Extract the ZIP file anywhere

Step 3: Right-click install.bat → Run as administrator

Step 4: Open Microsoft Word → See -- NORMAL -- in title bar 🎉

📁 wordvim-v0.1.0.zip
   └── 📁 wordvim
       ├── 📄 install.bat      ← Double-click this (as admin)
       ├── 📄 uninstall.bat
       ├── 📄 register.ps1
       ├── 📄 unregister.ps1
       ├── 📄 PoC.dll
       └── 📄 PoC.pdb

Option 2: Build from Source

# Prerequisites: .NET SDK 8.0+ and Git
git clone https://github.com/spidychoipro/wordvim.git
cd wordvim/poc
dotnet build

# Register (run PowerShell as administrator)
.\register.ps1

📖 Documentation

Document	Description
Architecture Analysis	Why COM Add-in + Win32 hooks, not VSTO or Office.js
API Research	Word COM API capabilities and limitations
MVP Specification	What the minimum viable product includes
Milestones	30-day development roadmap
PoC Plan	Proof of concept validation plan
Environment Guide	Development environment setup
Contributing	Contributor guidelines and code conventions

🏗️ Architecture

┌──────────────────────────────────────────────────────────────┐
│                      WordVim Architecture                    │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐     │
│  │   Win32     │    │   Word      │    │   Vim       │     │
│  │   Hook      │───▶│   COM API   │───▶│   State     │     │
│  │  (keyboard) │    │  (cursor)   │    │   Machine   │     │
│  └─────────────┘    └─────────────┘    └─────────────┘     │
│         │                  │                   │             │
│         ▼                  ▼                   ▼             │
│  ┌─────────────────────────────────────────────────────┐    │
│  │              COM Add-in (IDTExtensibility2)         │    │
│  │                  WordVim.Connect                    │    │
│  └─────────────────────────────────────────────────────┘    │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Component	Technology	Purpose
Add-in	COM + IDTExtensibility2	Load into Word process
Keyboard	WH_KEYBOARD hook	Intercept keystrokes before Word
Cursor	Word COM API	Move cursor, edit text
State	C# state machine	Track Insert/Normal mode

🎮 Usage

Key Bindings

Key	Mode	Action
Escape	Insert → Normal	Switch to Normal mode
i	Normal → Insert	Switch to Insert mode
h/j/k/l	Normal	Cursor movement (planned)
w/b/e	Normal	Word motions (planned)
x	Normal	Delete character (planned)
dd	Normal	Delete line (planned)
yy	Normal	Yank line (planned)

Mode Indicator

The window title bar displays the current mode:

-- NORMAL --  ← All keys except 'i' are swallowed
-- INSERT --  ← Normal typing mode

❓ FAQ

Does this work with Word Online?

No. WordVim requires the desktop version of Word 365 on Windows. Word Online uses a different architecture that doesn't support COM Add-ins.

Do I need Visual Studio?

No. WordVim builds with `dotnet build` — just install the .NET SDK.

Is this safe?

Yes. WordVim is open source (MIT License). The installer only registers a COM Add-in — no system files are modified.

How do I uninstall?

Right-click `uninstall.bat` → Run as administrator. Done.

🤝 Contributing

See CONTRIBUTING.md for contributor guidelines.

# Commit convention
feat(scope): description
fix(scope): description
docs: description

# Examples
feat(core): add w/b/e word motions
fix(hooks): prevent delegate GC collection
docs: update milestones with Phase 3

📊 Project Status

✅ Research & Architecture      ████████████ 100%
✅ PoC: Add-in Loading          ████████████ 100%
✅ PoC: Keyboard Hook           ████████████ 100%
✅ PoC: Mode Switching          ████████████ 100%
🔜 Phase 0: Foundation          ░░░░░░░░░░░░   0%
🔜 Phase 1: Core Engine         ░░░░░░░░░░░░   0%
🔜 Phase 2: Word Integration    ░░░░░░░░░░░░   0%
🔜 Phase 3: Commands            ░░░░░░░░░░░░   0%
🔜 Phase 4: Visual Mode         ░░░░░░░░░░░░   0%
🔜 Phase 5: Release v1.0        ░░░░░░░░░░░░   0%

📄 License

MIT License — free to use, modify, and distribute.

🙏 Acknowledgments

• Vim — the legendary text editor that inspired this project
• Word Object Model — Microsoft's COM API for Word automation
• WH_KEYBOARD Hook — Win32 API for keyboard interception

---

Built with ❤️ for Vim users who are stuck with Word

⬆️ Back to top