Refine: AI Grammar Checker for Obsidian

An offline, local-first AI grammar checker and writing assistant for Obsidian on Mac, powered by a local LLM.

Install in Obsidian · Download Refine for Mac

Refine is an AI grammar checker powered by a local language model, so it can run entirely offline. This plugin brings its contextual grammar, spelling, and fluency suggestions to Obsidian, helping you improve your notes without leaving your editor.

Features:

• Offline checks powered by a downloaded local LLM on your device
• Inline highlights and suggestion cards for reviewing changes in context
• Clear explanations of why each change is suggested

Requirements

• macOS 14 or later
• Obsidian desktop 1.5.0 or later
• Refine for Mac 1.35 or later

Refine is free to use for grammar and fluency checks, with no account or credit card required.

Install

1. Download Refine for Mac, open it, and complete setup.
2. In Obsidian, open Settings → Community plugins → Browse.
3. Search for Refine, then select Install and Enable. You can also open the Refine plugin in Obsidian.
4. Keep Refine running and open a Markdown note in Editing view. The plugin connects to Refine automatically.

Check a note

Open a Markdown note in Editing view. With Check Writing Automatically enabled (the default in Refine), the active note is checked after you pause typing briefly.

1. Hover over highlighted text to open its suggestion card.
2. Review the change and inspect the language and model used for the check. If the action is available, choose Explain for more context.
3. Choose Apply to accept the correction or Dismiss to ignore it. When Refine offers Report, selecting it explicitly sends feedback about that live suggestion; reports are never submitted automatically.

The Refine icon in Obsidian's status bar shows the connection, checking progress, and suggestion count. Select it to open the Refine menu. To check on demand, open the Command Palette and run Refine: Check current note.

Suggestion colors, highlighting, automatic checks, local or hosted models, and Quick Apply shortcuts are configured in the Refine app. Choose Custom shortcut… for Apply or Dismiss to record combinations such as Option+Right Arrow. The full physical key and modifier set must match; plain Tab and arrows retain their normal behavior when a custom combination is selected. Both the app and plugin must support custom shortcuts. Older versions continue using the previous single-key bindings identified in Refine settings.

Modifier-only shortcuts support holding two or more exact left/right modifier keys, then releasing them, or double-tapping one modifier within half a second. Choose Held modifiers or Double-tap modifier in Refine's recorder. Typing another key or changing the active suggestion cancels a pending gesture. Both Refine and Obsidian need gesture support; older integrations keep the previous bindings shown in Refine settings.

Privacy and offline use

The plugin sends the complete active Markdown note to the Refine app over a same-user Unix socket so Refine can check it. With a downloaded local model, the source and model response stay on your Mac, and writing checks can run without an internet connection after the model is downloaded.

To find the running Refine app, the plugin reads a small endpoint descriptor file in ~/Library/Application Support/com.runjuu.refine/ outside your vault. It reads no other files outside the vault.

Refine can also use hosted providers that you configure. In that case, requests from the Refine app—including note source—may go to the selected provider and are subject to that provider's privacy and retention policies.

Report is separate from the writing-check provider. Only choosing Report on a live suggestion can send feedback to Refine's feedback service, and only when Refine makes that action available. A report may contain original and revised snippets plus language, provider, model, custom-instruction, Refine version, and macOS version context. The plugin does not automatically report suggestions.

This plugin does not send its own analytics or persist note source. It keeps the active integration state in memory; Obsidian and any other installed plugins have their own logging, telemetry, and retention behavior. App and model downloads, updates, optional license services, hosted checks, and Report require internet access.

Learn how Refine handles your writing or read the privacy policy.

Troubleshooting

Refine is not connected

Make sure Refine is installed, open, and up to date. Then select the Refine icon in Obsidian's status bar to see the current connection state. The plugin reconnects automatically after Refine restarts. If the exact Integration Protocol versions differ, the plugin reports both versions and asks for a compatible Refine/plugin pair; it does not guess which component is newer.

Refine did not understand the plugin

The installed Refine app cannot read what this plugin sends, which happens when Refine is older than the plugin. Update Refine for Mac, then reopen the note.

No suggestions appear

Open a Markdown note in Editing view and confirm that Refine is running and has completed setup. Check the Check Writing Automatically setting in Refine, or run Refine: Check current note from the Command Palette.

A suggestion cannot be applied

Refine will not apply a stale correction if the note changed after it was checked, or if the note is read-only. Check the current note again and review the new suggestion.

Frequently asked questions

Is Refine a private Grammarly alternative for Obsidian?

Refine is a local-first AI writing assistant for Mac. With a downloaded local model, it can check grammar, spelling, and fluency in Obsidian without sending your writing to a cloud model. Its grammar and fluency checks are free to use and require no account. Refine requires its Mac app; it is not a standalone Obsidian plugin.

Does Refine work completely offline?

Writing checks can run offline with a downloaded local model. Downloads, updates, hosted models, and optional license services still require a connection. Free grammar and fluency checks do not require license activation. If you have a purchased lifetime license, you can use Offline Activation for advanced features during longer disconnected use.

Does the plugin work on Windows, Linux, or mobile?

No. Refine for Obsidian currently requires the Refine app on macOS and therefore works only in Obsidian desktop on Mac.

Can Refine check an entire vault or Reading view?

No. The plugin checks the active Markdown note in Editing view. It does not run vault-wide checks or check Reading view.

Get started

Ready to use a local AI grammar checker in Obsidian? Download Refine for Mac, then install Refine from Obsidian Community Plugins.

Support

For plugin bugs and feature requests, open a GitHub issue. For help with the Refine app, email [email protected].

Refine supports same-user macOS writing-host clients connecting to the shipping Refine server with exact Integration Protocol 1.0. Protocol 1.0 compatibility is maintained throughout Refine 1.x. The support profile does not include network transports, cross-user access, other operating systems, sandbox workarounds, automatic app launch, or third-party production servers, and it does not include an integration- development SLA or certification program. Conformance is self-assessed; there is no approval gate or compatibility badge.

The public statement “Compatible with Refine Protocol 1.0” has additional conditions: each advertised release must pass the conformance suite and make the source-flow, Report destination/data, explicit Report gesture, and client telemetry/retention disclosures. See the protocol package's support profile and compatibility-claim conditions.

Refine for Obsidian is available under the MIT License.

Development

npm install
npm run typecheck
npm test
npm run build

To run the protocol package's eight live AF_UNIX conformance scenarios against the production transport/runtime seams, point the opt-in conformance command at a local refine-protocol checkout:

REFINE_PROTOCOL_ROOT=/path/to/refine-protocol npm run test:conformance

This external-repository gate is intentionally separate from npm test; the normal test suite does not require a protocol checkout.

Partial-check passage details use the optional com.runjuu.refine.check-diagnostics.v1 capability. The draft extension vectors are in test/fixtures/check-diagnostics-v1.json; the immutable base-protocol fixtures remain unchanged. Before releasing this extension, publish its specification and registry entry in refine-protocol, pin that published revision, and rerun the client and protocol conformance suites. Until then, only DEBUG builds of the Refine app activate the draft capability. Production and older Refine servers continue to show the partial status and offer Retry current note.

The plugin retains bounded coordinate metadata for historical revisions, without note text; diagnostics for an unknown or evicted revision end the integration because their source coordinates can no longer be validated.

For local testing, copy manifest.json, main.js, and styles.css into .obsidian/plugins/refine/ in a test vault, then reload Obsidian and enable Refine under Community plugins.

The integration boundaries and safe-Apply semantics are documented in the Refine Integration Protocol 1.0 specification, which is the supported public wire. It is an exact-version, local macOS client-to-Refine interface. Endpoint permissions, peer-UID checks, and a per-launch token exclude other OS users and nonlocal peers; self-reported client labels do not authenticate one process from another process already running as the same user.