Legibility is a CLI that configures and runs legibility linters on code, folder structure, and text for humans and agents.
The goal is a set of minimal tools making programming easier to reason about for all giving a little joy back to programming.
You’ll see the word “joy” a lot here. That’s intentional.
3 sentences for why you might want to use Legibility
Each Legibility linter runs on its own, and each plugin works with its corresponding linter. Use the CLI once to choose your tools and save their arguments. Keep using it to run those checks.
Why Legibility was built
Legibility’s goal is to make agentic programming more enjoyable.
Although, agentic coding and large language models have solved many programming problems and sped it up generally, it has also created new problems. These new problems require new solutions. Or, in the case of Legibility, a new way of defining what high quality joyous programs look like.
Preface
As agents write more code, skills help enforce clear patterns. Linters and plugins check those patterns automatically. The goal is to make code easier to read, write, and compile, even when working with thousands of lines a day.
This README documents the initial CLI contract.
Install
For stable releases, install with Homebrew:
brew install yowainwright/tap/legibility
Or install the npm package:
npm install legibility -g
Homebrew installs a native binary and does not require Node.js. The npm package requires Node.js 24 or newer.
Run
From a project directory, start guided setup or run the discovered configuration.
Setup detects project languages, offers supported linters, previews commands, and asks before saving legibility.json or running checks. It requires a terminal; non-interactive runs need an existing configuration.
Hosted linters like ESLint and Oxlint stay project-managed dependencies. Setup can use Homebrew to install Legibility's native linters.
Example
1. Command
legibility
2. Generated output
Select TypeScript and an available Oxlint integration, then approve the save. Legibility writes:
my-project/└── legibility.json
For example, entering --deny-warnings as the Oxlint arguments produces:
Full reference: run legibility --help.
The examples below assume legibility is on PATH.
legibility
Type: command
Runs the project's enabled linters. With no configuration, interactive runs start guided setup. Setup previews commands and asks before saving legibility.json or running a linter. Non-interactive runs require an existing configuration.
legibilitylegibility --dry-run
Use --dry-run to inspect selected linter commands before execution.
legibility update
Type: command
Refreshes Homebrew metadata and offers updates for supported Homebrew-backed linters.
An eligible interactive run also checks for Homebrew linter updates before linting.
legibility update
Use this to update linters without running the project's checks. See updates configuration for prompt and enablement behavior.
Set updates.prompt to false to make eligible updates non-interactive:
With the default updates.prompt: true, legibility update requires an interactive terminal. Setting it to false refreshes Homebrew metadata and applies all eligible updates without prompting.
legibility rules [--search <terms>]
Type: command
Searches the shared rule catalog. Search terms use AND matching across rule content and mappings.
legibility rules --search "function length"
Use this to find a rule by ID, name, description, example, language, or tool.
The shared rule catalog documents rule mappings and coverage.
The LEG038 example illustrates a refactor under a three-line limit:
- function renderTitle(value) {- const title = value.trim();- return title;- }+ function renderTitle(value) {+ return value.trim();+ }
--search <terms>
Type: string option
Filters rules results. Every space-separated term must match; matching is case-insensitive. Without this option, Legibility prints the rule count and a search hint.
legibility rules --search "function length"
Search only reports matching rules; it does not change files. After finding LEG038, you can enable its Oxlint mapping with the legibility rule command:
Shows rule details and a language/plugin mapping. Add --language or --plugin to select a mapping. Add --enable to enable a supported Oxlint mapping; use --dry-run to preview the edit.
Example output with no project Legibility config or Oxlint config:
LEG038 — max-function-linesLimit functions to a focused line budget.Topics: functions, complexityJavaScript · Oxlint · native rule: max-lines-per-function Coverage: JavaScript: Provided by native linter Default: disabled Settings: max: number; skipBlankLines: boolean; skipComments: boolean; IIFEs: boolean; Preset Recommended: warn {"max":40,"skipBlankLines":true,"skipComments":true,"IIFEs":true} Project: disabled (no Oxlint config; documented default) Legibility runner: not configured Docs: https://github.com/yowainwright/legibility/blob/main/docs/rules.md#leg038-javascript-typescript-oxlint
Automatic edits support simple Oxlint JSON and JSONC configs. Inherited, overridden, nested, and TypeScript configs are reported as unsupported.
--language <name>
Type: string option
Filters rule details to a language mapping. Use a language ID or label.
legibility rule LEG038 --language typescript
--plugin <name>
Type: string option
Filters rule details to a plugin mapping.
legibility rule LEG038 --plugin oxlint
--enable
Type: boolean option
Default: false
Enables the selected supported rule mapping in a simple Oxlint JSON or JSONC configuration. Requires both --language and --plugin. Use --dry-run to preview the edit.
Type: string option
Default: discover config from the current directory and parents; start setup if none is found in a terminal
Reads a JSON Legibility config or a package.json with a legibility object. Legibility reports an error if automatic discovery finds more than one config.
Passes remaining arguments to one selected linter, after its configured arguments. Legibility rejects native arguments when multiple linters are selected.
With the quick-start config, this appends the path after the saved arguments:
"oxlint" "--deny-warnings" "src"
--dry-run
Type: boolean option
Default: false
Prints selected linter commands or previews a supported rule edit without running linters or writing the edit. Also skips the automatic Homebrew update check. legibility update --dry-run is not supported.
legibility --dry-run
--help, -h, --version, -v
Type: boolean options
Prints the CLI reference or installed version.
legibility --helplegibility --version
--verbose
Type: boolean option
Default: false
Prints diagnostic logs to stderr while leaving native linter output on its original streams.
legibility --verbose
--styleguide
Type: boolean option
Opens an interactive tour of the setup prompts. Does not save configuration, install tools, update Homebrew, or run linters.
legibility --styleguide
Configuration
Legibility reads JSON configuration from a file or from package.json#legibility.
The field examples below are excerpts. Combine them in one config with at least one enabled linter.
Legibility searches the current directory and its parents. It stops with an error if it finds more than one config. Use --config to select a file explicitly.
Type: string[] or an object keyed by language ID
Optional
Records the languages selected during setup. Setup writes a string array when there are no per-language settings. The object form reserves space for those settings; none currently affect execution. Configured linter IDs determine which tools run.
{ "languages": ["typescript", "go"]}
linters
Type: object
Required: yes
Maps supported linter IDs to their settings. A run needs at least one enabled linter.
These standalone Legibility commands are registered by the CLI. Configure each ID under linters.
Each Legibility config below is a complete .legibilityrc. The commands preview the invocation; remove --dry-run to execute it with the underlying tool installed.
fs-lint
Command: fs-lint – Languages: all detected languages
Checks file and path policy. Define the native policy in fs-lint.json (reference):
Configure these integrations under linters. Each entry lists the command Legibility invokes.
Each Legibility config below is a complete .legibilityrc. Install the integration and configure its native rules before executing checks.
Measurements are from one local environment and are not guarantees. Targets describe planned work for a later CLI iteration.
CLI startup
Current: 20–30 ms in the measured environment
Startup is already quick. Lazy loading the rule catalog is not a release target unless later measurements show it matters.
Setup scan
Target: under 3 seconds on a representative large repository
Setup uses an ignore-aware file inventory, fixed filename and extension lookups, bounded path samples, and up to eight concurrent manifest reads (diagnosis, file inventory). Git projects use Git's file inventory; non-Git projects apply local .gitignore rules during traversal. The earlier 6–14 second measurement predates this implementation.
Homebrew check
Current: 5.5 seconds before linting in the measured interactive run
Target: check at most once a week by default
Eligible interactive runs check for updates before linting (checkForUpdates). The planned weekly interval will be configurable in project config and via a CLI option. No interval setting or option exists yet; updates currently controls enablement, manager, and prompting.
Linter concurrency
Current: sequential
Target: a small bounded parallel limit by default
Linters run one at a time (runLinters). The planned parallel limit will be adjustable in project config and via a CLI option. Concurrency is not configurable yet, and the default limit is undecided.
Run feedback
Current: per-linter duration is visible with --verbose
Target: compact per-linter progress and a clear summary, using pastels
Legibility currently forwards native linter output directly. The agreed summary and pastel progress output are not part of the current CLI yet.
Exit status
Type: process exit status
0 – successful setup, update, preview, or linter run.
2 – CLI, configuration, or process-start error.
130 – interactive prompt cancelled.
The first non-zero linter status passes through unchanged. Setup and explicit update commands may also return child-process statuses.
Because child statuses pass through, a linter may also return 2; the exit status alone does not always identify whether Legibility or a linter failed.
Agent skill
The npm package includes skills/legibility-workflow/SKILL.md. Agent integrations can install it as a project skill to route setup and check execution through the CLI.
Development
Use Node.js 26 and pnpm for development. The package supports Node.js 24 and newer.
pnpm installpnpm run checkpnpm testpnpm run test:e2e