# Known Issues with Automattic/Harper: Core Engine Bugs and Integration Limitations

> Discover known issues in Automattic/harper including core engine bugs like dialect defaults and coordinate translation errors. Learn about integration limitations and false positives.

- Repository: [Automattic/harper](https://github.com/Automattic/harper)
- Tags: known-issues
- Published: 2026-07-27

---

**TLDR**: Automattic/harper contains documented known issues across its multi-project grammar-checking ecosystem, including hard-coded American dialect defaults in `harper-core`, coordinate translation bugs in the desktop highlighter, and TODO-marked dictionary entries that trigger false spelling positives.

Harper is an open-source grammar-checking ecosystem developed by Automattic that spans a core Rust engine (`harper-core`), command-line tools, desktop applications, and browser extensions. While the project provides robust linting capabilities, the source code contains numerous **known issues** documented via inline TODO comments, architecture notes, and GitHub issue references. Understanding these limitations helps developers implement workarounds and contributors prioritize fixes.

## Core Engine Known Issues (harper-core)

The core library implements the parsing, tokenization, and rule-execution pipeline. Most known issues are flagged within the linting modules and dictionary files.

### Parsing and Configuration Limitations

**Incremental parsing** is not yet implemented in the Tree-Sitter wrapper. According to the source code in [[`harper-tree-sitter/src/lib.rs`](https://github.com/Automattic/harper/blob/main/harper-tree-sitter/src/lib.rs)](https://github.com/Automattic/harper/blob/master/harper-tree-sitter/src/lib.rs#L26), the wrapper currently re-parses entire documents rather than using Tree-Sitter's incremental capabilities, which could improve performance on large documents.

The **Markdown parser lacks user-configurable options** for spelling detection. In [[`harper-wasm/src/lib.rs`](https://github.com/Automattic/harper/blob/main/harper-wasm/src/lib.rs)](https://github.com/Automattic/harper/blob/master/harper-wasm/src/lib.rs#L65), the parser configuration is currently hard-coded, preventing users from customizing which elements get spell-checked.

### Grammar Rule False Positives

The **Weir rule "ThereToTheir"** inadvertently matches sentences containing the phrase "known issues." The rule file at [`harper-core/src/linting/weir_rules/ThereToTheir.weir`](https://github.com/Automattic/harper/blob/master/harper-core/src/linting/weir_rules/ThereToTheir.weir#L50) contains an inline example demonstrating this false positive.

**Compound noun detection** is broken in the LinkedList rule due to issue #3741. The file [`harper-core/src/linting/weir_rules/LinkedList/Singular.weir`](https://github.com/Automattic/harper/blob/master/harper-core/src/linting/weir_rules/LinkedList/Singular.weir#L8) contains a direct TODO comment referencing this known issue.

The **`replace_with_match_case` utility** produces incorrect casing in pluralization scenarios. As noted in [[`harper-core/src/linting/over_plus.rs`](https://github.com/Automattic/harper/blob/main/harper-core/src/linting/over_plus.rs)](https://github.com/Automattic/harper/blob/master/harper-core/src/linting/over_plus.rs#L132), the utility can incorrectly preserve casing (e.g., "Plus" vs "plus") when generating suggestions.

### Dictionary and Spelling Issues

Certain **dictionary entries trigger false positives** due to TODO markers embedded in the word list. The file [`harper-core/dictionary.dict`](https://github.com/Automattic/harper/blob/master/harper-core/dictionary.dict#L53870) contains entries like "ANN" and "FAT" that are flagged incorrectly because they were marked with internal TODO comments during data entry.

### Dialect and Localization Gaps

Many lints are **hard-coded to American English**, limiting localization support. The `there_is_agreement` linter in [[`harper-core/src/linting/there_is_agreement.rs`](https://github.com/Automattic/harper/blob/main/harper-core/src/linting/there_is_agreement.rs)](https://github.com/Automattic/harper/blob/master/harper-core/src/linting/there_is_agreement.rs#L614) contains TODO notes indicating that dialect-specific rules need implementation for British and other English variants.

**Progressive verb forms** are not fully supported in the metadata system. According to [[`harper-core/src/linting/looking_forward_to.rs`](https://github.com/Automattic/harper/blob/main/harper-core/src/linting/looking_forward_to.rs)](https://github.com/Automattic/harper/blob/master/harper-core/src/linting/looking_forward_to.rs#L20), this affects suggestions for phrases like "looking forward to," which may generate incomplete or incorrect recommendations.

## Command-Line Interface Limitations (harper-cli)

The CLI tool has known gaps in file handling and text processing.

**Custom dictionary paths** are not supported via command-line flags. The [`main.rs`](https://github.com/Automattic/harper/blob/main/main.rs) file at [[`harper-cli/src/main.rs`](https://github.com/Automattic/harper/blob/main/harper-cli/src/main.rs)](https://github.com/Automattic/harper/blob/master/harper-cli/src/main.rs#L281) contains TODO placeholders indicating that workspace dictionary configuration remains unimplemented, hampering multi-project setups.

**Newline detection** may misinterpret line endings when scanning raw source text. The linting module in [[`harper-cli/src/lint.rs`](https://github.com/Automattic/harper/blob/main/harper-cli/src/lint.rs)](https://github.com/Automattic/harper/blob/master/harper-cli/src/lint.rs#L783) contains comments noting that carriage return and line feed handling requires improvement for cross-platform consistency.

## Desktop Application Bugs (harper-desktop)

The Tauri-based desktop client has specific issues with UI integration and coordinate systems.

**Highlighter coordinate translation** fails on secondary monitors. The accessibility API returns global screen coordinates while overlay windows use local monitor origins, causing misalignment on multi-monitor setups. This is documented in the architecture notes and affects files in `harper-desktop/src-tauri/src/highlighter/`.

**macOS accessibility ranges** struggle with UTF-8 to NSString conversion for emoji and non-BMP characters. This leads to inaccurate text selection ranges when the highlighter attempts to select text containing multi-byte characters.

The **Report Issue UI** contains an unimplemented feature. The tray menu code in [[`harper-desktop/src-tauri/src/tray.rs`](https://github.com/Automattic/harper/blob/main/harper-desktop/src-tauri/src/tray.rs)](https://github.com/Automattic/harper/blob/master/harper-desktop/src-tauri/src/tray.rs#L21) includes a "Report Issue" button that is not wired to an automated feedback collector.

## Browser and IDE Integration Issues

Extensions for VS Code and browsers inherit limitations from the core engine while adding their own integration challenges.

**Lazy initialization** of lint boxes in the WordPress plugin requires optimization. The file [[`packages/wordpress-plugin/src/harper/useLintBoxes.ts`](https://github.com/Automattic/harper/blob/main/packages/wordpress-plugin/src/harper/useLintBoxes.ts)](https://github.com/Automattic/harper/blob/master/packages/wordpress-plugin/src/harper/useLintBoxes.ts#L85) contains a TODO indicating that the current initialization logic creates unnecessary overhead.

**Markdown parser configurability** limitations from `harper-wasm` propagate to all JavaScript-based extensions, preventing users from customizing parsing behavior in the VS Code extension and browser plugins.

## Workarounds for Common Issues

While awaiting official fixes, developers can implement temporary solutions for several known issues.

### Using Custom Dictionaries with the CLI

Although the CLI lacks a `--dict` flag, you can use the `HARPER_DICTIONARY` environment variable respected by the underlying core engine:

```bash

# Create a temporary dictionary file

echo "mycustomword" >> my_dict.txt

# Run Harper CLI with custom dictionary

HARPER_DICTIONARY=my_dict.txt harper-cli lint "This is a test with mycustomword."

```

### Filtering American-English False Positives

When the `there_is_agreement` linter incorrectly flags British English usage, filter the suggestions programmatically:

```javascript
import { LocalLinter } from "harper.js";

const linter = new LocalLinter({ dialect: "american" });
const result = await linter.lint("There is a hotel.");

// Remove specific dialect-based suggestions
const filtered = result.suggestions.filter(
  s => s.message !== "Use ‘a’ before ‘hotel’"
);

```

### Fixing Desktop Highlighter Coordinates

For secondary monitor alignment issues, adjust the coordinate translation in a custom build:

```rust
// In harper-desktop source
let global_rect = highlighter.get_global_rect();
let monitor_origin = highlighter.get_monitor_origin();

let local_rect = Rect {
    x: global_rect.x - monitor_origin.x,
    y: global_rect.y - monitor_origin.y,
    ..global_rect
};

```

## Summary

- **Core engine limitations** include hard-coded American dialect defaults, incomplete incremental parsing in Tree-Sitter bindings, and TODO-marked dictionary entries causing false spelling flags.
- **CLI restrictions** prevent custom dictionary path configuration and exhibit newline handling inconsistencies across platforms.
- **Desktop application bugs** involve coordinate misalignment on secondary monitors and unimplemented macOS accessibility range conversions for non-BMP characters.
- **Extension issues** propagate core parser limitations while adding lazy initialization overhead in the WordPress plugin.
- **Workarounds** exist for dictionary loading (environment variables), dialect filtering (post-processing suggestions), and coordinate translation (custom builds).

## Frequently Asked Questions

### How can I contribute fixes for these known issues?

Contributors should focus on files containing TODO comments, particularly in `harper-core/src/linting/` for grammar rules and `harper-cli/src/` for interface improvements. The repository uses standard GitHub issue tracking, and pull requests should reference specific line numbers where known issues are documented.

### Are there workarounds for the American dialect limitations?

Yes. When using [`harper.js`](https://github.com/Automattic/harper/blob/main/harper.js), filter the suggestions array to remove dialect-specific recommendations, or use the core library directly with modified rule sets. The CLI currently respects the `HARPER_DICTIONARY` environment variable for adding British English variants to your local word list.

### Why does the desktop highlighter misalign on my second monitor?

The highlighter uses global screen coordinates from the accessibility API but renders overlays using local monitor origins. Until the coordinate translation logic in `harper-desktop/src-tauri/src/highlighter/` is updated, use the application on your primary monitor or apply the manual coordinate offset fix demonstrated in the workarounds section.

### Which known issues affect the VS Code extension specifically?

The VS Code extension inherits the Markdown parser configurability limitations from `harper-wasm` and shares the core engine's dialect handling constraints. Additionally, the extension cannot currently override the hard-coded spelling parser configuration, limiting customization options compared to direct API usage.