This guide explains all the settings available in TextWarden and how they affect your experience. Access settings via the TextWarden menu bar icon → Preferences.
- Table of Contents
- General Settings
- Updates
- Grammar & Language
- Custom Vocabulary
- Readability
- AI Style Suggestions
- Sketch Pad
- Appearance
- Application Controls
- Keyboard Shortcuts
- Advanced Settings
- Troubleshooting Tips
- Getting Help
What it does: Automatically starts TextWarden when you log into your Mac.
Recommendation: Enable this for always-on grammar checking without having to remember to launch the app.
TextWarden uses Sparkle for secure, automatic updates. Update settings are found in Preferences → About.
When you check for updates (manually or automatically), TextWarden:
- Securely connects to the update server over HTTPS
- Downloads an update feed signed with EdDSA cryptographic signatures
- Compares your version against available releases
- If a newer version is available, shows a dialog with release notes and options to update now or skip
All updates are code-signed by the developer and notarized by Apple, ensuring they haven't been tampered with.
What it does: When enabled, TextWarden checks for updates once every 24 hours in the background. If an update is found, you'll see a notification.
Default: Disabled (opt-in for privacy)
Recommendation: Enable this to stay up to date with bug fixes and new features without having to remember to check manually.
What it does: Opts you into the experimental update channel, which includes pre-release versions (alpha and beta builds) in addition to stable releases.
What you'll get:
- Stable channel (default): Only production releases (e.g., 1.0.0, 1.1.0)
- Experimental channel: Pre-release versions (e.g., 0.1.0-alpha.3, 1.1.0-beta.1) plus stable releases
When to enable:
- You want to try new features before they're officially released
- You're willing to report bugs and provide feedback
- You understand that experimental releases may have rough edges
When to keep disabled:
- You prefer stability over new features
- You rely on TextWarden for critical work
Note: Experimental releases go through the same code signing and notarization process as stable releases—they're not less secure, just less tested.
Click Check for Updates in the About section to immediately check for available updates. This shows the update dialog if a newer version is available, or confirms you're up to date.
What it does: Determines spelling and grammar rules. For example, "colour" vs "color", "analyse" vs "analyze".
Options:
- American English
- British English
- Canadian English
- Australian English
- Indian English
Recommendation: Choose the dialect matching your audience or workplace standards.
What it does: When enabled, TextWarden detects non-English text and skips grammar checking. If more than 60% of a document is in an excluded language, all checking is skipped for that document. For mixed-language documents, each sentence is analyzed and foreign-language sentences are skipped while English sentences are still checked.
Excluded Languages: Specify which languages to ignore (e.g., German, French, Spanish). Documents primarily written in these languages will be skipped entirely.
Recommendation: Enable if you write in multiple languages. This prevents false positives on foreign text while still checking your English writing.
What it does: Choose which types of errors TextWarden flags.
Categories include:
- Spelling - Misspelled words
- Grammar - Subject-verb agreement, tense consistency
- Punctuation - Missing or incorrect punctuation (with sub-options, see below)
- Style - Wordiness, passive voice, clichés
- Capitalization - Proper nouns, sentence starts
- Repetition - Repeated words like "the the"
Recommendation: Enable all categories initially. Disable specific ones only if they generate too many unwanted suggestions for your writing style.
When the Punctuation category is enabled, additional fine-tuning options appear:
- Oxford Comma - Flag lists missing the serial comma (e.g., "apples, bananas and oranges" → "apples, bananas, and oranges")
- Ellipsis Formatting - Suggest proper ellipsis character (…) instead of three periods (...)
- Unclosed Quotes - Flag quotation marks that are opened but never closed
- Dash Usage - Check correct usage of em-dashes (—), en-dashes (–), and hyphens (-)
All sub-options are enabled by default. Disable individual rules if they don't match your preferred writing style.
What it does: Words you add here will never be flagged as spelling errors. Useful for names, technical terms, brand names, and jargon specific to your field.
How to add words:
- Click "Add Word" and type the term
- Or right-click any flagged word → "Add to Dictionary"
TextWarden includes optional word lists you can enable:
- Internet Abbreviations - Common online terms (lol, btw, imo, etc.)
- Gen Z Slang - Modern slang terms (vibe, slay, bussin, etc.)
- IT Terminology - Technical terms (kubernetes, nginx, oauth, etc.)
- Brand Names - Company and product names (iPhone, LinkedIn, etc.)
- Person Names - Common first and last names
Recommendation: Enable the lists matching your typical writing context. Developers might enable IT Terminology; social media managers might enable Internet Abbreviations and Gen Z Slang.
What it does: Respects words you've already taught to macOS via "Learn Spelling" in other apps (like Safari, Mail, or Pages). This avoids having to add the same words twice.
How it works: TextWarden checks each flagged word against macOS's spell checker to see if you've previously learned it.
Note: This is read-only. Words you add via TextWarden go into TextWarden's own Custom Dictionary (below), not the macOS system dictionary.
Default: Enabled
Recommendation: Keep enabled to automatically respect words you've already taught to macOS. Disable only if you want TextWarden to use a completely separate dictionary.
TextWarden analyzes text complexity using the Flesch Reading Ease formula. These settings are found in Settings → Style under the Readability section.
Note: Readability features work independently of Apple Intelligence and are available on all supported macOS versions.
What it does: Master toggle for all readability features. When enabled:
- Displays a Flesch Reading Ease score in the floating indicator (for text with 30+ words)
- Analyzes individual sentences for complexity
- Flags sentences that are too difficult for your target audience
- Provides AI-powered simplification suggestions (when Apple Intelligence is available)
Score interpretation:
| Score | Label | What it means |
|---|---|---|
| 90-100 | Very Easy | Easily understood by an average 11-year-old |
| 70-89 | Easy | Conversational English for consumers |
| 60-69 | Standard | Easily understood by 13-15 year olds |
| 50-59 | Fairly Difficult | Fairly difficult to read |
| 30-49 | Difficult | College-level reading |
| 0-29 | Very Difficult | Best understood by university graduates |
How it works: Click on the readability score in the indicator to see a detailed breakdown with improvement tips.
Default: On
What it does: Sets the expected reading level for your audience. TextWarden uses this to determine which sentences are "too complex" and need simplification suggestions.
Options:
| Audience | Min Flesch Score | Description |
|---|---|---|
| Accessible | 65+ | Everyone should understand (~8th grade level) |
| General | 50+ | Average adult reader (~10th grade level) |
| Professional | 40+ | Business readers (~12th grade level) |
| Technical | 30+ | Specialized readers (college level) |
| Academic | 20+ | Academic/research (graduate level) |
How it works: Sentences with a Flesch score significantly below (10+ points) the threshold for your selected audience are flagged. Short sentences (<12 words) are not flagged.
Default: General (50+ Flesch score)
Recommendation: Match this to your audience. Use "Accessible" for public-facing content, "Professional" for business documents, "Technical" for developer documentation.
What it does: Controls whether violet dashed underlines appear under complex sentences. Only available when readability analysis is enabled.
Default: On
Use case: Disable this if you want readability scoring and AI simplification suggestions but find the visual underlines distracting.
Requires: macOS 26 (Tahoe) or later with Apple Intelligence enabled
At the top of this section, you'll see the current availability status of AI features:
- Ready - Apple Intelligence is available and working
- Not Available - Shows the reason (not enabled, device not eligible, or macOS version too old)
If Apple Intelligence isn't enabled, you can click "Open Settings" to configure it in System Settings.
What it does: Activates AI-powered writing enhancement features:
- Style Suggestions - Get suggestions for clarity, tone, and conciseness
- AI Compose - Generate text from instructions by clicking the pen icon in the indicator
All processing happens locally on your device using Apple Intelligence.
Style checking runs automatically after grammar analysis with smart rate limiting. You can also trigger it manually via keyboard shortcut or by clicking the style section of the indicator.
What you'll see: When enabled, you may get suggestions like "Consider rephrasing for clarity" or "This could be more concise."
What it does: Tailors suggestions to match your intended tone.
Options:
- Default - Balanced improvements for general writing
- Formal - Professional tone, complete sentences, suitable for business documents
- Casual - Friendly, conversational, good for emails to friends or social media
- Business - Clear, action-oriented, ideal for professional communication
- Concise - Removes filler words and unnecessary verbosity
Recommendation: Match this to your current task. Switch between styles as needed—formal for reports, casual for Slack messages.
What it does: Controls how creative vs. consistent the AI suggestions are.
Options:
- Consistent - Same input produces same suggestions (deterministic)
- Balanced - Slight variation while maintaining accuracy
- Creative - More varied suggestions, still appropriate for writing tasks
Recommendation: Use Consistent for professional documents where you want predictable results. Use Balanced for everyday writing.
Sketch Pad is TextWarden's built-in writing environment with full AI integration. Access it via the menu bar icon → Sketch Pad or the keyboard shortcut (default: ⌥⌃P).
- Drafting content - Write emails, messages, or documents in a focused environment before copying to your target application
- Unsupported applications - When an application doesn't work well with TextWarden's accessibility integration, compose in Sketch Pad and paste
- Full AI access - Get grammar checking, style suggestions, readability analysis, and AI quick actions all in one place
Real-time Analysis
- Grammar and spelling errors are underlined as you type
- Style suggestions appear when AI analysis completes
- Readability score updates in real-time
Insights Panel The right sidebar shows all detected issues organized by category:
- Correctness - Spelling and grammar errors (red)
- Style - Tone and word choice improvements (purple)
- Clarity - Readability and complexity issues (blue)
Click any insight to see the suggestion and apply it.
AI Assistant The AI Assistant section provides quick actions and custom prompts:
-
Quick Actions - One-click buttons for common transformations:
- Professional - Formal, business-appropriate tone
- Friendly - Warm, conversational style
- Concise - Removes unnecessary words
- Refine - General polishing and improvement
-
Custom Prompt - Enter your own instructions for the AI (e.g., "Make this more persuasive" or "Simplify for a general audience")
-
Scope - Quick actions apply to selected text, or the entire document if nothing is selected
Undo Support
All AI-generated changes can be undone with ⌘Z, so you can experiment freely and revert if needed.
- Select specific text before using quick actions to transform only that portion
- Use the readability score to gauge if your text matches your target audience
- The Insights panel shows a count of issues - aim for zero before copying your final text
What it does: Controls the overall look of TextWarden's interface.
Options:
- System - Follows your Mac's appearance setting
- Light - Always light mode
- Dark - Always dark mode
What it does: Controls the appearance of suggestion popovers and indicators.
Options:
- System - Matches your Mac's appearance
- Light - Light background for popovers
- Dark - Dark background for popovers
What it does: How transparent the suggestion popover appears.
Range: 50% (more transparent) to 100% (fully opaque)
Recommendation: If popovers feel too prominent, reduce opacity. If they're hard to read, increase it.
What it does: Size of text in suggestion popovers.
Range: Small to Large
Recommendation: Adjust based on your display and visual preferences.
What it does: Thickness of the wavy underlines shown under errors.
Range: Thin to Thick
Recommendation: Thicker lines are more noticeable but may feel intrusive. Find your balance.
What it does: Where the floating indicator appears relative to the text field.
Options:
- Auto - TextWarden chooses based on available space
- Top Right - Above and to the right
- Bottom Right - Below and to the right
- Top Left - Above and to the left
- Bottom Left - Below and to the left
You can drag the indicator to any position along the window border, and positions are remembered per application.
What it does: When enabled, the indicator remains visible even when there are no grammar errors or style suggestions, displaying a green checkmark as confirmation that everything is fine.
Why you'd enable it: Provides constant visual feedback about your text quality. When Apple Intelligence is enabled, also gives quick mouse access to Style Check and AI Compose features.
Default: Off. The indicator only appears when there are grammar errors or style suggestions.
What it does: Controls how long you need to hover over the indicator before the suggestion popover appears.
Range: 0ms (instant) to 1000ms
Default: 0ms (instant display)
Recommendation: Keep at 0ms for immediate feedback. Increase the delay if you find the popover appearing too quickly when you're just moving the mouse across the screen.
TextWarden organizes applications into two categories based on their support level.
What they are: Applications that TextWarden has been tested and optimized for. These have dedicated configuration profiles that ensure accurate underline positioning and proper text replacement.
Default behavior: Active (grammar checking enabled)
Examples: Slack, Claude, Safari, Apple Mail, Microsoft Word, Apple Notes, and many more. See the full list in Settings → Applications.
What they are: Applications discovered on your system that don't have a dedicated configuration profile. Grammar checking may work, but visual underlines might be inaccurate.
Default behavior: Paused indefinitely on first discovery. This prevents unexpected behavior in apps where TextWarden hasn't been tested.
How to enable: You can manually set any "Other" application to Active in Settings → Applications. Your choice persists across restarts.
Request support: Want TextWarden to fully support an app you use? Click the "Request" button in the Other Applications section to submit a feature request.
What they are: Command-line applications like Terminal, iTerm2, Warp, and others.
Default behavior: Paused indefinitely. Grammar checking in terminals typically produces false positives from command output, error messages, and code snippets.
How to enable: You can manually enable any terminal if desired, though this isn't recommended.
Options for each app:
- Active - TextWarden monitors and checks text
- Paused for 1 Hour - Temporarily disabled, automatically resumes
- Paused for 24 Hours - Temporarily disabled, automatically resumes
- Paused Until Resumed - Disabled until you manually re-enable
Use cases:
- Pause for apps where you intentionally write unconventionally
- Pause during presentations or screen sharing
- Enable an "Other" application you want to try with TextWarden
Each application row has an underline button (U) that lets you enable or disable visual error underlines for that specific app, independent of grammar checking. This is useful when:
- You want grammar checking but find underlines distracting
- An app has positioning issues that make underlines inaccurate
What it does: Quickly pause TextWarden across all applications.
How to use: Click the menu bar icon → select a pause duration
Options:
- 15 minutes
- 1 hour
- 4 hours
- Until tomorrow
- Indefinitely
TextWarden supports global keyboard shortcuts that work in any application.
| Action | Default | Description |
|---|---|---|
| Toggle TextWarden | ⌥⌃T | Enable/disable grammar checking globally |
| Fix All Grammar Errors | ⌥⌃A | Apply all single-suggestion grammar fixes at once |
| Action | Default | Description |
|---|---|---|
| Show Grammar Suggestions | ⌥⌃G | Toggle the grammar suggestions popover |
| Show Style Suggestions | ⌥⌃Y | Toggle the style suggestions popover |
| Show AI Compose | ⌥⌃W | Toggle the AI text generation popover |
| Show Readability | ⌥⌃R | Toggle the readability score popover |
| Run Style Check | ⌥⌃S | Trigger manual style analysis |
| Action | Default | Description |
|---|---|---|
| Accept Suggestion | Tab | Apply the current suggestion |
| Dismiss Suggestion | ⌥Esc | Dismiss without applying |
| Previous Suggestion | ⌥← | Navigate to previous error |
| Next Suggestion | ⌥→ | Navigate to next error |
| Apply Suggestion 1 | ⌥1 | Apply first suggestion option |
| Apply Suggestion 2 | ⌥2 | Apply second suggestion option |
| Apply Suggestion 3 | ⌥3 | Apply third suggestion option |
- Open Preferences → Shortcuts tab
- Click on any shortcut to record a new key combination
- Press your desired keys
- Click elsewhere to confirm
Tip: Choose shortcuts that don't conflict with your most-used applications.
Known Conflicts:
- Apple Mail:
⌥⌃A(Fix All Obvious) may conflict with some application shortcuts. Consider customizing if needed.
These settings are found in Preferences → Diagnostics.
What it does: Controls what information TextWarden records for diagnostics.
Log Levels:
- Error - Only serious problems
- Warning - Potential issues
- Info - General operation info (default)
- Debug - Detailed technical info, may include analyzed text
- Trace - Everything, may include analyzed text (generates large log files)
Privacy Note: At Info level and above, logs contain only metadata (character counts, hashes, etc.) without your actual text. When you select Debug or Trace level, TextWarden displays a warning because these levels may include portions of analyzed text for troubleshooting purposes. Be mindful of what text you analyze and who you share log files with when using verbose logging.
File Logging: When enabled, writes logs to disk for later review. You can choose a custom log file location or use the default (~/Library/Logs/TextWarden/textwarden.log).
Recommendation: Keep at "Warning" or "Info" for normal use. Enable "Debug" only when troubleshooting issues, and be aware of the privacy implications.
What it does: Shows colored borders around detected text fields. Useful for troubleshooting positioning issues.
Options:
- Text Field Bounds - Where TextWarden thinks the text area is
- Window Coordinates - Raw window position data
- Cocoa Coordinates - Converted screen coordinates
Recommendation: Keep disabled unless troubleshooting. These are developer tools.
What it does: Creates a ZIP file containing system information, settings, and logs to help troubleshoot issues. Access via Preferences → Diagnostics → Export Diagnostics.
What's Included:
- System information (macOS version, hardware, memory)
- All TextWarden settings (grammar rules, word lists, UI preferences)
- Usage statistics (words analyzed, corrections applied, app usage)
- Recent log files (sanitized for privacy)
- Crash reports (if any)
- List of applications used with TextWarden
Privacy Protections:
- Text content protected at default levels - At Info level and above, logs only contain metadata (e.g., "analyzed 50 chars"). Debug and Trace levels may include text for troubleshooting (see Logging Configuration).
- Path anonymization - File paths are sanitized (e.g.,
/Users/[REDACTED]/Documents/...) - Sensitive data filtering - Lines containing passwords, tokens, keys, or secrets are automatically removed from logs
- Custom dictionary excluded - Your personal dictionary words are not included
What's NOT Included (at default log levels):
- Text you've typed or analyzed
- Personal dictionary entries
- Authentication credentials
- Private document content
Note: If you've enabled Debug or Trace logging, the diagnostic export may contain portions of analyzed text. Consider switching back to Info level before exporting if privacy is a concern.
Recommendation: Before sharing a diagnostic export, unzip it and review the contents. This lets you verify exactly what's included and feel confident about what you're sharing.
Suggestions aren't appearing:
- Check that TextWarden is running (look for the menu bar icon)
- Verify the app isn't paused (icon should not show a pause indicator)
- Ensure the current application isn't in the paused list
Too many suggestions:
- Disable grammar categories that don't apply to your writing
- Add frequently-flagged terms to your custom dictionary
- Enable appropriate word lists (IT Terminology, etc.)
Style checking unavailable:
- Requires macOS 26 (Tahoe) or later
- Apple Intelligence must be enabled in System Settings → Apple Intelligence & Siri
- Requires an Apple Silicon Mac (M1 or later)
Underlines in wrong position:
- Try a different application if possible—some apps have limited accessibility support
- Check Debug Overlays to see what TextWarden detects
- Report the issue with a diagnostic export (Help → Export Diagnostics)
- Troubleshooting Guide: See TROUBLESHOOTING.md
- Report Issues: GitHub Issues
- Export Diagnostics: Preferences → Diagnostics (see Diagnostic Export for privacy details)