aesthetics

README

Make taste explicit.
Aesthetics evaluates code, documentation, and changes against the qualities you care about.

Linters check what a program can decide. Aesthetics checks what takes judgment: clarity, organization, composition, coherence, simplicity.

You write guidelines in plain language, or adopt a school of thought such as unix, kiss, or diataxis. You decide where each one applies. A decision model judges every guideline and reports pass, fail, or indeterminate. Every failure comes with a recommendation and, where it can, the lines that show the problem.

_{A 90-second narrated intro with subtitles · transcript}

Install

curl -fsSL https://raw.githubusercontent.com/sadasant/aesthetics/main/install.sh | sh

The script downloads the release for your macOS or Linux machine, verifies its checksum, and installs it. Prefer something else?

• Go 1.22+: go install github.com/sadasant/aesthetics/cmd/aesthetics@latest
• Binaries for macOS, Linux, and Windows: Releases

Quick start

export OPENAI_API_KEY=…             # or TypeSafe, Cloudflare, a self-hosted Laya, …
aesthetics init --use unix,kiss     # writes .aesthetics.yaml
aesthetics check                    # the whole repository
aesthetics check --diff             # only what you changed
aesthetics explain src/main.go      # which guidelines apply, and why

The tutorial walks through a first evaluation in about ten minutes.

Your taste, written down

# .aesthetics.yaml
provider: openai
extends: [unix, kiss, atomic]            # schools of thought, nothing implicit

guidelines:
  - Error messages say what failed and what the user can do about it.

rules:
  - match: "**/README.md"
    extends: [readme]
  - match: "src/**/utils/**"
    guidelines:
      - Avoid abstractions with a single caller.

Guidelines can be scoped to paths, file types, directory depths, directories, the whole repository, or Git diffs. Rules compose and specialize them. When schools of thought disagree, the higher-ranked guideline governs, and explain shows exactly why.

Preset	Foundation	Judges
unix	Unix philosophy	Focused responsibilities, simple interfaces, composability
kiss	Keep It Simple	Directness and the absence of unnecessary complexity
atomic	Atomic changes	Focused, coherent diffs without unrelated edits
readme	Standard Readme	Purpose, installation, usage, orientation
diataxis	Diátaxis	Documentation organized by what readers need
solid	SOLID	Cohesion, responsibilities, abstractions, dependencies

What makes it different

• Your judgment, not ours. No guideline is on by default, and no school of thought is treated as universally right.
• Context, not just files. It evaluates files by their role (an entry point is not a README), directories by their organization, the repository by its coherence, and diffs as changes.
• Honest about uncertainty. Each outcome comes from a calibrated probability. When the model can't decide, the result says so.
• Fair to your history. On a diff, every failure is marked as introduced by the change or preexisting, and by default only introduced problems fail CI.
• Built for CI. It runs non-interactively, returns meaningful exit codes, writes a JSON report, and never modifies your files.
• Measured. Evals with 104 labeled judgments set its defaults: 97% correct on clear cases with OpenAI and 98% with Cloudflare Clef, with no false failures.

Documentation

When you want to	Read
Learn	Tutorial: your first evaluation
Do	Write your own guidelines · Check changes in CI · Configure a provider
Look up	CLI · Configuration · Presets · Providers · Results and exit codes
Understand	How evaluation works · How guidelines compose

Contributing

Issues and pull requests are welcome. Keep changes focused and run go test ./.... If a change affects judgments (presets, question wording, or the context sent to models), run go run ./evals before and after, and include both summaries. The repository evaluates itself with aesthetics check.

License

Aesthetics is released under the MIT License.