How to Install and Use Harper in Linux for a Fast Offline Developer Grammar Checker

Writing technical documentation, open-source README files, pull request descriptions, code comments, and commit messages is an integral part of everyday software engineering. However, traditional word-processing grammar checkers fall short for programmers: they frequently misinterpret camelCase variables, code blocks, technical jargon, and Markdown formatting as grammatical errors. Furthermore, many commercial writing assistants require uploading your private source code to third-party cloud servers, posing significant security and privacy compliance risks.

Harper is a modern, blazing-fast, offline grammar checker written entirely in Rust and designed specifically for developers. Created by Elijah Potter, Harper runs 100% locally on your Linux machine with zero cloud dependencies. It natively parses Markdown files, code comments, and docstrings while understanding programming syntax. Harper can be run as a standalone command-line linter, integrated into Git pre-commit hooks, or connected directly to text editors (including Neovim, Helix, and VS Code) via the Language Server Protocol (LSP). This guide explains how to install Harper on Linux, audit Markdown and code files, configure custom developer dictionaries, and integrate Harper into your local workflow.

Why Choose Harper Over Traditional Grammar Tools?

Harper addresses the specific friction points software developers experience when writing documentation:

• Extreme Speed and Low Resource Usage: Compiled in Rust, Harper checks tens of thousands of words in milliseconds without consuming gigabytes of system memory.
• Code and Markup Awareness: Correctly ignores inline code snippets (`like_this()`), fenced code blocks, URL links, HTML tags, and snake_case or camelCase variables.
• Zero Cloud Telemetry: Operates entirely offline, making it ideal for enterprise air-gapped development, defence contracting, and privacy-sensitive codebases.
• Native LSP Integration: Includes harper-ls, a Language Server Protocol binary that brings instant inline diagnostics, squiggle warnings, and code actions to modern terminal editors.

Step 1: Installing Harper on Linux

Harper provides precompiled binaries, Cargo package installation, and installation scripts.

Method A: Installing via Precompiled Standalone Binaries (Universal)

The fastest way to install Harper on any x86_64 Linux distribution is downloading the latest release binary directly from GitHub:

# Download the latest Linux x86_64 binary release
curl -LO https://github.com/Automattic/harper/releases/latest/download/harper-cli-x86_64-unknown-linux-musl.tar.gz

# Extract the archive
tar -xzf harper-cli-x86_64-unknown-linux-musl.tar.gz

# Move the executable binary to your system execution path
sudo mv harper-cli /usr/local/bin/harper

# Verify the installation and check the version
harper --version

Method B: Installing via Rust’s Cargo Package Manager

If you have the Rust toolchain installed on your Linux machine:

cargo install harper-cli --locked

Method C: Installing the Language Server (harper-ls)

If you intend to use Harper inside Neovim, Helix, or VS Code, install the companion language server:

cargo install harper-ls --locked

Step 2: Checking Documentation and Markdown Files via CLI

To inspect a Markdown file, technical specification, or README for grammatical errors, run the lint subcommand:

harper lint README.md

Harper outputs precise diagnostics indicating line numbers, columns, grammatical explanations, and suggested replacements:

README.md:14:23: Did you mean "an" instead of "a"?
  14 | This repository provides a open-source framework for distributed systems.
     |                          ^
Suggestion: "an"

Checking Entire Documentation Directories

You can recursively lint all documentation files across a repository:

harper lint docs/

Step 3: Checking Code Comments and Docstrings

Harper natively understands programming languages including Rust, Python, Go, JavaScript, TypeScript, C, and C++. When you run Harper against a source code file, it extracts and lints only comments and docstrings while ignoring executable code:

# Lint comments inside a Python script
harper lint src/main.py

# Lint docstrings inside a Rust codebase
harper lint src/lib.rs

Step 4: Customising the User Dictionary and Ignoring Jargon

Development projects often use company names, specialized API terms, and technical acronyms that standard dictionaries flag. Harper stores custom words in a plain-text user dictionary located at ~/.config/harper/dictionary.txt:

1. Create the Harper configuration directory:

   mkdir -p ~/.config/harper

2. Open or create your custom dictionary:

   nano ~/.config/harper/dictionary.txt

3. Add your technical terms, one per line:

   Kubernetes
   PostgreSQL
   OAuth
   WebSockets
   gRPC
   Prometheus
   GraphQL

4. Save the file. Harper will now recognise these words as valid and omit warnings across all repositories.

Step 5: Integrating Harper into Git Pre-Commit Hooks

To catch grammatical errors and typos automatically before pushing commits to remote repositories, integrate Harper into your local Git hook:

cat << 'EOF' > .git/hooks/pre-commit
#!/usr/bin/env bash
set -e

# Run Harper against all staged markdown files
for file in $(git diff --cached --name-only --diff-filter=ACM | grep '\.md$'); do
    echo "Auditing $file with Harper..."
    harper lint "$file"
done
EOF

chmod +x .git/hooks/pre-commit

Harper Command Reference Summary

Command Syntax	Description / Action
harper lint <file>	Scans a specific Markdown, text, or source code file for grammatical issues
harper lint <directory>	Recursively checks all supported files inside a directory tree
harper --version	Displays the currently installed Harper CLI version
harper-ls	Launches the Language Server Protocol daemon for Neovim/Helix/VS Code