About
Built for developers who ship with AI.
Little Owl exists because the thing AI-assisted development erodes fastest is the thing no diff shows you: the shape of the project as a whole.
Principles
What it promises
A tool that reports structural problems only works if you believe it. Everything below is a constraint the implementation actually holds itself to.
- Deterministic, always
- The same code produces the same findings on every machine. No model, no sampling, no run-to-run variation. If it says there is a cycle, there is a cycle.
- Confidence is stated, not implied
- Dead code is graded high, medium or low. Impact lowers its own confidence when a dynamic import could reach further than it can see. Archaeology says when the history records no reason instead of inventing one.
- It reports patterns, never authorship
- The structural rules find duplicated helpers, parallel implementations and single-use abstractions. Those shapes appear whenever code is changed without seeing the whole project. Little Owl never claims to know who or what wrote a line.
- The baseline is yours
- It is never refreshed automatically. Moving the mark is an explicit act, because a baseline that drifts with the code hides exactly the degradation it exists to catch.
Scope
What it deliberately does not do.
Every one of these is handled better by a tool that already exists.
- It is not a linter
- ESLint, Ruff and golangci-lint answer “is this line acceptable?”. Little Owl answers “is this project in better or worse shape than before?”. Run both.
- It is not a security scanner
- For vulnerabilities, run your package manager’s audit command. Dependency findings here are hygiene only.
- It is not a test runner
- Test gaps are a risk signal from the import graph and naming. For real numbers, use a coverage tool.
- It is not a formatter
- It never edits your source. The only thing it writes is its own .little-owl/ directory.
Trust
False positives are bugs.
A tool that cries wolf gets ignored, and then all of its true findings are wasted too. A finding you would dismiss as intentional is a defect in Little Owl, not a disagreement about your code.
The repository has an issue template specifically for them. They are triaged like any other bug, and the rules already carry deliberate exemptions: a facade that delegates to two implementations is not duplication, a framework file with no importer is not dead, and a client component calling a server action is not a boundary violation.
Report a false positiveWhen a finding is wrong, say so with
- The rule id, which every finding prints
- A minimal snippet that triggers it
- Why the pattern is intentional in your project
- Your .little-owl/config.ts, if you have one
Every rule can also be turned down or off in configuration — but if it fires wrongly for you, it is probably firing wrongly for others.
Privacy
Your code stays on your machine.
This is not a policy promise. There is no network code in the package.
No source-code uploads
Your files are read from disk and never leave it.
No backend
There is no service to be down, rate-limit you, or shut off.
No authentication
No account, no login, no seat count.
No API key
Nothing to provision before the first run.
No telemetry
Not opt-out — absent. There is no analytics code to disable.
No AI required
Little Owl never calls a model. It writes prompts; you decide what to do with them.
Open source, MIT licensed
Issues, rule proposals and language adapters are all welcome. New rules need tests covering both the case that should fire and a case that must not — that requirement is in the pull request template for a reason.
Contact
Where to send what
Anything about the tool itself is better in the open, where the next person with the same question can find it. Everything else has an address.
- A bug, or a finding you disagree with
- Open an issue — there is a template for false positives, and they are triaged as bugs.
- A security problem
- Privately, never as a public issue — a GitHub security advisory or the address below.
- Anything else
- info@littleowlcode.com