Skip to content
Documentation menu

Getting started

There is no setup step. Point Little Owl at a project you already have and it will infer what it can, tell you when it is guessing, and print a report.

1. Run it

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

npx little-owl-code

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.

npm install -D little-owl-code
pnpm add -D little-owl-code

3. Read your first report

little-owl check

little-owl check

$ little-owl check
Name            storefront
Stack           Next.js · TypeScript
Package manager pnpm
Files           247
Git             ✓

CODEBASE HEALTH

Overall

  81 / 100
  ████████████████░░░░

Architecture     79
Maintainability  44
Complexity       96
Dependencies     76
Type Safety      98

🟡 87 warnings   🔵 63 notes   (150 total)

FINDINGS

🟡 architecture  ui imports infrastructure directly
   src/app/(app)/panel/config/page.tsx:17

   panel/config/page.tsx imports lib/db/client.ts,
   skipping the application layer. The detected
   structure is ui -> application -> infrastructure.

   found:    ui -> infrastructure
   expected: ui -> application -> infrastructure

   → Route the call through application
     instead of importing infrastructure here.

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.

The severities

Findings come in three levels, and the distinction matters: only errors fail a build by default.

MarkerLevelMeans
🔴errorStructurally wrong. Fails CI by default.
🟡warningWorth a look. Does not fail a build unless you say so.
🔵infoContext. Never gates anything.

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.

little-owl baseline

5. The loop

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

After an AI-assisted change

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.

little-owl init

This writes .little-owl/config.ts and, optionally, an initial baseline. Both belong in version control.

If the output looks wrong

little-owl doctor

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.