Getting started

1. Run it#

The fastest way in needs nothing installed. Requires Node.js 18.18 or newer.

In a terminal this opens interactive mode, which lists what it detected and offers the handful of things you probably want. When output is piped or the CI environment variable is set, it falls back to a plain health report instead.

2. Install it properly#

For repeated use — and for CI — add it as a development dependency so the version is pinned in your lockfile.

3. Read your first report#

The scores

Six numbers between 0 and 100. Each starts at 100 and loses points for measurable problems, normalised by project size so a large repository is not punished for being large.

• They are for comparing a project to its own past. Comparing them across different projects means very little.
• Every point is traceable. Architecture falls for cycles, inverted dependencies and skipped layers, each with a fixed weight.
• The findings are the product. The score is a summary of them, not a verdict on your work.

What it decided not to look at

Before any findings, init prints what is in scope and what it skipped. Fixtures, __mocks__, examples/, testdata/ and *.stories.* are excluded by default — that code is deliberately broken or purely illustrative, and findings about it are all true and all useless.

If one of them really is your application, put the pattern back with a ! in ignore: ignore: ['!examples/**']. And if the output ever looks like it is describing someone else's project, little-owl doctor checks exactly that.

The priorities

Findings come in three levels, and the distinction matters: only the top one fails a build by default.

Two vocabularies for one fact. Rules are configured with error, warning and info, matching every other linter config you have ever written. Reports speak in priorities, because that is what tells you how urgently something needs your time. Both appear in --json, as severity and priority.

Working through one issue

Every issue is numbered, and the number is the same in every command. You never have to describe a finding to Little Owl — you point at it.

explain answers what happened, why it matters, where it is and what should happen instead — in plain language, with the technical detail one flag away. fix 1 then names the files involved and writes a brief precise enough to hand to an AI assistant, and verify 1 confirms the change actually landed. Little Owl never edits your source itself.

4. Record a baseline#

A baseline is what turns a list of findings into a signal about change. Once it exists, little-owl review shows only what is new, and existing debt stops being repeated at you every run.

5. The loop#

This is the whole workflow. Let your assistant work, then ask what it did to the project.

little-owl review --scope 'src/features/orders/**'
little-owl prompt        # a fix brief built from the real findings
little-owl review        # again, against the same baseline

The scope flag is optional but worth using: it is what catches an assistant editing files outside the area you asked about.

Optional: declare your structure#

Without configuration, layers are inferred from your directory names and every report says so. If you want boundary checks you can rely on, declare them once.

It asks nothing — the stack, the structure and the layers are read from the files on disk, and it prints what it found before writing anything. Pass --interactive to choose them yourself.

This writes .little-owl/config.ts, LITTLE_OWL.md — the briefing file Claude Code, Cursor and similar assistants read before touching the project — and, optionally, an initial baseline. All of them belong in version control. --no-agent-file skips the briefing file; little-owl agent writes it on its own later.

If the output looks wrong#

Every check is about Little Owl's own ability to do its job here: whether it found your source files, whether imports resolved, whether git is available, whether the scan covered the whole project. It is the first thing to run when a report surprises you.