swadhin / opengrammar public

Swadhin Biswas

[email protected]

2026-03-27 22:00:26 +0600 committed NaN years ago

3cf9224

commit 3cf9224

1 file changed

+41 -38

Files

README.md +41 -38

Showing 1 changed file+41-38

README.md

▼README.md

+41-38

@@ -1,78 +1,81 @@
1	1	<div align="center">
2	2	<img src="logo.svg" alt="OpenGrammar Logo" width="120" height="120">
3	3
4		- # 🪶 OpenGrammar
	4	+ # 🪶 OpenGrammar 2.0
5	5
6	6	Your privacy-first, open-source writing assistant.
7		- The free, self-hostable Grammarly alternative.
	7	+ The completely free, zero-compromise Grammarly alternative you can host yourself.
8	8
9	9	[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
10	10	[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)
11		- [![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/swadhinbiswas/opengrammar?utm_source=oss&utm_medium=github&utm_campaign=swadhinbiswas%2Fopengrammar&labelColor=171717&color=FF570A&link=https%3A%2F%2Fcoderabbit.ai&label=CodeRabbit+Reviews)](https://coderabbit.ai)
12	11	[![React](https://img.shields.io/badge/React-20232A?style=flat-square&logo=react&logoColor=61DAFB)](https://reactjs.org/)
13	12	[![Vite](https://img.shields.io/badge/vite-%23646CFF.svg?style=flat-square&logo=vite&logoColor=white)](https://vitejs.dev/)
14	13	</div>
15	14
16	15	---
17	16
18		-OpenGrammar is a powerful, self-hostable browser extension that helps you write clearly and confidently everywhere on the web. It's built to feel like the premium writing assistants you know, but with a critical difference: you control your data, and it can run completely for free.
	17	+Writing clearly matters. But achieving perfect grammar shouldn't mean sacrificing your privacy or paying a premium monthly subscription to a tech giant.
	18	+
	19	+Welcome to OpenGrammar—a powerful, robust browser extension built from the ground up to match the premium writing tools you already know, but with one massive difference: You own your data, and it runs completely for free.
19	20
20	21	## 🌟 Why OpenGrammar?
21	22
22		-Most popular grammar assistants require you to send every keystroke to their servers and charge a hefty monthly fee for advanced features. OpenGrammar changes that:
	23	+For too long, the industry standard has been to quietly siphon every keystroke you type to remote servers, locking advanced features behind hefty paywalls. OpenGrammar is our answer to that:
	24	+
	25	+1. The Zero-Cost Foundation: Out of the box, our core engine runs 100% locally in your browser. With a massive 156,000-word offline dictionary, it instantly catches misspellings, passive voice, and weak phrasing without ever pinging a server.
	26	+2. Bring Your Own Brain (BYOK): Want deep, context-aware AI corrections? Just plug in your own API key (OpenAI, Groq, Together, OpenRouter, or even local open-source models via Ollama). You pay fractions of a cent exclusively for what you use, cutting out the middleman entirely.
	27	+3. Paranoid-Level Privacy: We don't have a database. We don't want your user data. Your API key never leaves your browser storage. If you choose to use the AI features, your text is processed through a stateless edge function and immediately deleted.
	28	+4. Deploy It Yourself: Trust no one? Perfect. You can deploy our lightweight backend to Cloudflare Workers or Vercel Edge for free, in a single command. You own the entire pipeline.
23	29
24		-1. Zero Cost Option: The core engine runs locally in your browser, checking for passive voice, repetition, and readability without needing a server or an internet connection.
25		-2. Bring Your Own AI: Want advanced, context-aware grammar corrections? Just paste in your own API key (like OpenAI, Groq, or OpenRouter). You pay only fractions of a cent for what you actually use, directly to the AI provider.
26		-3. Absolute Privacy: We don't have a database. We don't have user accounts. Your API key never leaves your browser. If you use the AI features, your text is sent securely to a stateless edge function, processed, and immediately forgotten.
27		-4. Open Source & Self-Hosted: You can deploy the backend to Cloudflare Workers or Vercel Edge for free in one command. You own the infrastructure.
	30	+## ✨ Under The Hood
28	31
29		-## ✨ Features
	32	+OpenGrammar 2.0 isn't just a wrapper—it's a dual-engine powerhouse.
30	33
31		-- Blazing Fast & Works Everywhere: Seamlessly integrates into text inputs, textareas, and rich text editors (like Gmail, Google Docs, Notion, and Reddit). Built with modern React, Vite, and Manifest V3.
32		-- Advanced Dual-Engine Architecture:
33		- 1. Rule-Based Engine (Free & Offline): Powered by a 156,000-word offline dictionary with Damerau-Levenshtein edit-distance and phonetic matching. Features 40+ granular grammar rules including subject-verb agreement, sentence fragments, and commonly confused words (affect/effect).
34		- 2. AI-Powered Engine (Bring Your Own Key): Use OpenAI, Groq, Together, OpenRouter, or local Ollama. The engine uses advanced prompting and deduplication logic—it never wastes LLM tokens on issues the offline engine already caught.
35		-- Smart Context Awareness: The engine automatically detects the domain you are writing in (Business Email, Technical Document, Chat, etc.) and adjusts its strictness accordingly.
36		-- Tone & Style Rewriting: Right-click context menus or shortcuts (Ctrl+Shift+R) to instantly rewrite highlighted text in 8 different tones.
	34	+- Blazing Fast & Works Everywhere: We seamlessly inject directly into text inputs, textareas, and complex rich-text editors (Gmail, Google Docs, Notion, Reddit). Built on React, Vite, and Manifest V3 so it never bogs down your browser.
	35	+- The Dual-Engine Architecture:
	36	+ 1. The Offline Sentinel: A Damerau-Levenshtein edit-distance and phonetic matching spellchecker catches immediate typos. 40+ granular grammar rules instantly flag subject-verb agreement issues, sentence fragments, and commonly confused words (like affect/effect).
	37	+ 2. The AI Enforcer: An intelligent LLM router. Thanks to our Deduplication Logic, the AI is completely aware of what the Offline Sentinel already caught. It never wastes expensive tokens repeating basic fixes.
	38	+- Smart Context Awareness: Are you writing a casual tweet, a highly technical documentation page, or a formal business email? The engine automatically detects your domain and scales its strictness appropriately.
37	39	- Deep Analytics & History:
38		- - Dynamic Writing Score: Evaluates your text (0-100) based on Correctness, Readability, Engagement (vocabulary diversity), and Delivery (sentence length variation).
39		- - Daily Tracking: Silently and privately tracks your daily writing history, words checked, and average score directly in your browser.
40		-- Intuitive UI: Familiar red, yellow, and blue underlines with interactive click-to-apply tooltips and a dedicated stats dashboard popup.
	40	+ - Dynamic Writing Score: Evaluates your text dynamically from 0-100 based on your Correctness, Readability, Engagement (vocabulary diversity), and Sentence Delivery variation.
	41	+ - Private Daily Tracking: Silently logs your writing history, words checked, and average daily score directly to your local extension storage.
	42	+- Tone & Style Rewriting: Right-click context menus or a quick `Ctrl+Shift+R` to instantly rethink highlighted text into 8 different tones.
	43	+- Flawless UI: The classic red, yellow, and blue squiggly underlines you grew up with, paired with slick, interactive click-to-apply tooltips and a gorgeous stats dashboard.
41	44
42	45	## 🚀 Getting Started (For Users)
43	46
44		-Note: Since this is an open-source developer project, it is not yet published on the Chrome Web Store. You will need to load it manually.
	47	+Note: As an open-source tool in active development, OpenGrammar is currently installed via developer mode.
45	48
46		-1. Download the Extension: Download the latest release or clone this repository.
47		-2. Open Extensions Page: In Chrome, go to `chrome://extensions/`.
	49	+1. Download the Extension: Grab the latest release or clone this repository.
	50	+2. Open Extensions Page: In Chrome/Brave/Edge, navigate to `chrome://extensions/`.
48	51	3. Enable Developer Mode: Toggle the switch in the top right corner.
49	52	4. Load Unpacked: Click the "Load unpacked" button and select the `opengrammar/extension/dist` folder you built or downloaded.
50		-5. Configure: Click the OpenGrammar icon in your browser toolbar. Paste your OpenAI, Groq, or OpenRouter API key to enable advanced AI capabilities.
	53	+5. Configure: Click the OpenGrammar feather icon in your browser toolbar. Paste in your OpenAI, Groq, or OpenRouter API key to unlock the advanced AI engine.
51	54
52	55	## 💻 Developer Guide: Build & Deploy
53	56
54		-Want to build OpenGrammar from scratch or deploy your own backend? Here is how.
	57	+Want to build OpenGrammar from scratch or deploy your own serverless backend? Let's get to it.
55	58
56	59	### Prerequisites
57	60
58	61	- Node.js (v18 or newer)
59		-- Bun (recommended) or npm/pnpm
	62	+- [Bun](https://bun.sh/) (Highly Recommended) or npm/pnpm
60	63
61	64	### 1. Set up the Backend (Serverless Edge API)
62	65
63		-The backend is a lightweight Hono API that securely handles AI translation requests.
	66	+Our backend isn't a bloated server. It's an ultra-lightweight Hono API that securely masks and handles AI routing.
64	67
65	68	```bash
66	69	# Navigate to the backend folder
67	70	cd opengrammar/backend
68	71
69		-# Install dependencies
	72	+# Install dependencies lightning fast with Bun
70	73	bun install
71	74
72	75	# Run locally for testing (runs on http://localhost:8787)
73	76	bun run dev
74	77
75		-# Deploy to Cloudflare Workers (requires a free Cloudflare account)
	78	+# Deploy globally to Cloudflare Workers (requires a free Cloudflare account)
76	79	bun run deploy
77	80	```
78	81
@@ -85,24 +88,24 @@ cd opengrammar/extension
85	88	# Install dependencies
86	89	bun install
87	90
88		-# Build the extension
	91	+# Build the extension into an optimized bundle
89	92	bun run build
90	93	```
91	94
92		-This will create a `dist/` folder. Load this folder into Chrome following the user instructions above.
	95	+The build process will generate a `dist/` folder. Load this folder into your browser following the user instructions above!
93	96
94		-## 🤝 Contributing & Help Needed
	97	+## 🤝 Join the Rebellion
95	98
96		-We need your help to make OpenGrammar the best open-source writing assistant!
	99	+We need your help to unseat the monopolies and make OpenGrammar the definitive open-source writing assistant.
97	100
98		-One of our primary goals is to build the most comprehensive library of local (offline) grammar and style rules.
	101	+Our biggest mission right now is building the ultimate library of local (offline) grammar and style rules. You don't even need to be a software engineer to contribute—if you're a language nerd with a good eye for grammar, we want you!
99	102
100		-- 📚 Add Grammar Rules: Help us expand `analyzer.ts` with more regex-based rules for common mistakes, style improvements, and clarity checks. See [GRAMMAR_RULES.md](./GRAMMAR_RULES.md) for a guide on how to add them.
101		-- 🐛 Report Bugs: Found a website where the highlighting is wonky? Open an issue!
102		-- 💡 Suggest Features: Have an idea for a cool new feature? Let's discuss it in the Discussions tab.
	103	+- 📚 Add Grammar Rules: Help us expand `analyzer.ts` with more regex-based rules for common mistakes, style improvements, and clarity checks. See our [GRAMMAR_RULES.md](./GRAMMAR_RULES.md) guide.
	104	+- 🐛 Hunt Bugs: Found a weird website where the text highlighting breaks? Open an issue.
	105	+- 💡 Dream Up Features: Have an idea for something cool? Start a thread in our Discussions tab.
103	106
104		-Please check out our [CONTRIBUTING.md](./CONTRIBUTING.md) and `ROADMAP.md` for more details.
	107	+Check out our [CONTRIBUTING.md](./CONTRIBUTING.md) and peek at the `ROADMAP.md` to see where we're headed next.
105	108
106	109	## 📄 License
107	110
108		-This project is licensed under the Apache 2.0 License - see the LICENSE file for details.
	111	+This project is open-source and proudly licensed under the Apache 2.0 License. See the LICENSE file for details. Let's build the future of writing together.
109	112