Polonius
"Brevity is the soul of wit." — Polonius, Hamlet Act 2, Scene 2
A VS Code extension that analyses your prose in real-time and highlights writing issues with colour-coded decorations — inspired by hemingwayapp.com. Integrates with GitHub Copilot for AI-powered rewrites.
Features
Colour-Coded Highlights
Polonius highlights five categories of writing issues directly in your editor:
| Colour |
Category |
What it catches |
| 🔴 Red |
Very hard to read |
Sentences with ARI grade ≥ 14 and ≥ 14 words |
| 🟡 Yellow |
Hard to read |
Sentences with ARI grade 10–13 and ≥ 14 words |
| 🟢 Green |
Grammar |
Grammar issues detected by Copilot |
| 🔵 Blue |
Weakeners |
Adverbs, passive voice, qualifying phrases |
| 🟣 Purple |
Simpler alternative |
Complex words that have a simpler replacement |
Hover Suggestions
Hover over any highlighted text to see what the issue is and how to fix it. Complex words show simpler alternatives; weakeners explain why they weaken your prose.
Quick Fix Code Actions
Click the light-bulb icon (or press Ctrl+.) on any issue to apply a suggested fix directly.
Copilot Integration
@polonius Chat Participant — Ask Copilot to rewrite or simplify passages via the Chat panel.- Simplify Selection — Select text, right-click, and choose Polonius → Simplify Selection with Copilot.
- Rewrite with Copilot — Available as a Quick Fix code action on highlighted issues.
A dedicated sidebar panel shows your document's readability grade, word/sentence/paragraph counts, and a breakdown of issues by category.
Markdown-Aware
Polonius understands Markdown. It skips code blocks, frontmatter, and inline code so you only get feedback on your actual prose.
Commands
| Command |
Description |
Polonius: Toggle Highlights |
Turn analysis on or off |
Polonius: Show Stats Panel |
Open the sidebar stats view |
Polonius: Analyse Document |
Run analysis immediately |
Polonius: Simplify Selection with Copilot |
Rewrite selected text using Copilot |
Polonius: Rewrite with Copilot |
Rewrite a flagged passage using Copilot |
Configuration
All settings live under polonius.* in your VS Code settings:
| Setting |
Default |
Description |
polonius.enabled |
true |
Enable/disable Polonius |
polonius.languages |
["markdown", "plaintext"] |
Language IDs to analyse |
polonius.readability.hardThreshold |
10 |
ARI grade for "hard to read" |
polonius.readability.veryHardThreshold |
14 |
ARI grade for "very hard to read" |
polonius.readability.minWords |
14 |
Minimum words for readability checks |
polonius.grammar.enabled |
true |
Enable Copilot grammar checking |
polonius.grammar.debounceMs |
1500 |
Debounce for grammar checks (ms) |
polonius.highlights.veryHard |
true |
Highlight very hard sentences |
polonius.highlights.hard |
true |
Highlight hard sentences |
polonius.highlights.grammar |
true |
Highlight grammar issues |
polonius.highlights.weakeners |
true |
Highlight adverbs/passive/qualifiers |
polonius.highlights.complex |
true |
Highlight complex words |
polonius.debounceMs |
300 |
Debounce for style analysis (ms) |
Requirements
- VS Code 1.90.0 or later
- GitHub Copilot extension (for grammar checking and AI rewrites)
Installation
From the VS Code Marketplace
Search for Polonius in the Extensions view (Ctrl+Shift+X) and click Install.
From VSIX
- Download the
.vsix file from Releases
- In VS Code, run
Extensions: Install from VSIX... from the Command Palette
Development
# Install dependencies
npm install
# Build
npm run build
# Watch mode
npm run watch
# Run tests
npm test
# Package as VSIX
npm run package
License
MIT
